This chapter describes changes to the ObjectStore C++ API in Release 6.0. For changes to the collections API, see Collections.
The following classes have been changed, added, or removed:
protected: tix_exception *get_exception() const;Returns a pointer to the exception currently being signaled. If no exception is being signaled, returns 0 (false). See also basic_undo::has_exception().
basic_undo::has_exception()
New
protected: os_boolean has_exception() const;Returns nonzero (true) if an exception is being signaled; otherwise, returns 0 (false). To learn which exception is being signaled, see basic_undo::get_exception(). However, in cases where you do not need to know which exception is being signaled, has_exception() is faster than get_exception().
objectstore
Changed
The following members of this class have been changed:
static os_lock_timeout_exception *acquire_lock(
os_cluster *clstr,
os_lock_type access,
os_int32 milliseconds
);
Attempts to acquire a lock of the type specified by lock_type (either os_read_lock or os_write_lock) on the cluster specified by clstr. This must be specified in a top-level transaction. Locking a cluster is equivalent to acquiring locks on all the pages of the cluster. For example, acquiring a read lock on a cluster is equivalent to acquiring read locks on all the pages of the cluster. Acquiring a lock on a cluster does not preclude a client that has acquired a lock on a cluster from also requesting separate locks on individual pages of the cluster.
If the lock is successfully acquired, acquire_lock() returns 0.
Specifying a -1 value for the milliseconds argument means that acquire_lock() uses the cluster's current lock timeout value.
If the caller wants an infinite timeout and the cluster's timeout values are not -1, the caller could pass a very large value for the timeout (to be effectively infinite). It could also use objectstore::set_lock_timeout to set the default to -1 temporarily.
Specifying a 0 value for the milliseconds argument means that the attempt to acquire the lock does not wait at all if any concurrency conflict is encountered.
After an attempt to acquire a lock, if the time specified by milliseconds elapses without the lock's becoming available, an os_lock_timeout_exception* is returned. The timeout is rounded up to the nearest whole number of seconds. The os_lock_timeout_exception contains information on the circumstances preventing lock acquisition. It is the caller's responsibility to delete the os_lock_timeout_exception object when it is no longer needed.
If the attempt causes err_deadlock to be signaled in the current session, the transaction is aborted regardless of the value of the specified timeout.
objectstore::discriminant_swap_bytes()
Removed
Not supported; see Support for Persistent Unions.
objectstore::free_memory()
New
static void free_memory(void* memory_to_free)Releases persistent storage to which memory_to_free points. This function performs the same operation as the ObjectStore ::operator delete(); see ::operator delete().
void operator delete(void *p) {
if (objectstore::is_persistent(p)
objectstore::free_memory(p);
else
// your own transient delete operation
};
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
static os_allocation_strategy get_allocation_strategy();
Returns the current strategy for all databases when allocating storage for an object in a cluster. For information about the return values, see objectstore::os_allocation_strategy_least_space and objectstore::os_allocation_strategy_least_wait. See also objectstore::set_allocation_strategy().
objectstore::get_auto_open_mode()
Changed
Previous to Release 6.0, you called get_auto_open_mode() to retrieve the current settings for both the autoopen mode and the fetch policy. Release 6.0 still supports this use. However, it is obsolete and will not be supported at a later release.
static void get_auto_open_mode( auto_open_mode &mode );Call objectstore::get_fetch_policy() to retrieve the current fetch policy.
See objectstore::set_auto_open_mode().
objectstore::get_fetch_policy()
New
enum os_fetch_policy {
os_fetch_page,
os_fetch_segment,
os_fetch_stream,
os_fetch_cluster
};
static void get_fetch_policy(
os_fetch_policy &policy,
os_int32 &bytes
);
Retrieves the current fetch policy for all databases (not just the autoopened ones). An enumerator of type os_fetch_policy is returned in policy and the fetch quantum is returned in bytes. For more information about the arguments, see os_cluster::set_fetch_policy(). For information about setting the fetch policy, see objectstore::set_fetch_policy().
objectstore::get_locator_file()
Changed
static const char* get_locator_file();The return value has been changed to const.
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
static objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for all databases, segments, and clusters. For more information about the return value, see os_cluster::set_lock_option(). For more information about setting the lock option, see objectstore::set_lock_option().
objectstore::get_lock_timeout()
New
static os_int32 get_lock_timeout();Returns the time in milliseconds for which the current process will wait to acquire a lock. A value of -1 indicates that the process waits forever if necessary. The returned value applies to both read-locks and write-locks. For information about setting the timeout value, see objectstore::set_lock_timeout().
Note
get_lock_timeout() replaces the obsolete methods get_readlock_timeout() and get_writelock_timeout() that are defined by:
static void get_object_range(
void const *address,
void *&header_address,
os_unsigned_int32 &total_size
);
address is a pointer to a persistent object, or into the middle of a persistent object. header_address is set to the beginning of the object; if a header is associated with the object, header_address points to the beginning of the header. total_size is set to include the object itself, including any meta-data (such as a header) associated with the object.
static void get_object_range(
void const *address,
void *&base_address,
os_unsigned_int32 &base_size,
void *&header_address,
os_unsigned_int32 &total_size
);
address, header_address, and total_size have the same meanings as in the first overloading. base_address is set to the start of the object itself, and base_size is set to include only the object itself.
objectstore::get_propagate_on_commit()
New
static os_boolean get_propagate_on_commit();For use with ObjectStore/Single applications. The return value indicates when ObjectStore propagates committed data from the transaction log to the affected database. If the return value is nonzero (true), propagations occur whenever a top level transaction commits. This is the default.
If the return value is 0 (false), propagations occur when a database is closed and the program ends normally. If the program ends prematurely, some of the committed data in the log may not have been propagated to the database. This data will be propagated the next time ObjectStore is initialized or when objectstore::propagate_log() is called, provided that the correct transaction log exists at the time.
In client-server mode, propagation is controlled by server parameters, and get_propagate_on_commit() always returns false.
For information about setting when propagations occur, see objectstore::set_propagate_on_commit(). For additional information about the log file, see
static os_unsigned_int32 get_transaction_max_retries();Returns the number of times a lexical transaction is automatically retried after being aborted because of a deadlock. See also objectstore::set_transaction_max_retries().
This method is equivalent to os_transaction::get_max_retries(), which is obsolete and will be removed from the API in a future release.
objectstore::get_union_variant()
New
static os_unsigned_int16 get_union_variant(
void *address,
const char *type
);
Returns a number that corresponds to the currently active member object of a union in persistent memory. The arguments have the following meanings:
objectstore::lock_as_used
Changed
This enumerator is a possible argument to
Calling one of the set_lock_option() functions with an argument of own_page_write has the same effect as calling one of the following unsupported functions with a nonzero argument:
void return_memory(
void *address,
os_signed_int32 length,
os_boolean evict_now
);
The return type of this function has been changed to void.
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
static void set_allocation_strategy( os_allocation_strategy );
Sets the strategy to use when looking for space to allocate for an object in a cluster. This strategy applies to all databases, segments, and clusters unless specifically overridden by a subsequent call to objectstore::set_allocation_strategy() or to
objectstore::set_auto_open_mode()
Changed
Previous to Release 6.0, you called set_auto_open_mode() to set both the autoopen mode and the fetch policy. Release 6.0 still supports this use, but it is deprecated and will not be supported at a later release. Instead, Object Design recommends using the following overloading of set_auto_open_mode() to set the autoopen mode:
static void set_auto_open_mode( auto_open_mode mode );Call objectstore::set_fetch_policy() to set the fetch policy.
If you use set_auto_open_mode() to set the fetch policy, the policy applies to all databases, not just the autoopened ones.
static void set_client_name(const char *new_name);The char * argument has been changed to const.
objectstore::set_eviction_batch_size()
Removed
Not supported. objectstore::set_eviction_pool_size()
Removed
Not supported. objectstore::set_fetch_policy()
New
enum os_fetch_policy {
os_fetch_page,
os_fetch_segment,
os_fetch_stream,
os_fetch_cluster
};
static void set_fetch_policy(
os_fetch_policy policy = os_fetch_page,
os_int32 bytes = 0
);
Sets the fetch policy for all databases, and not just the autoopened ones. In all other respects, this method is the same as os_cluster::set_fetch_policy().
objectstore::set_lock_option()
New
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
static void set_lock_option(objectstore_lock_option);
Sets the locking behavior for all databases, segments, and clusters. In all other respects, this method is the same as os_cluster::set_lock_option().
objectstore::set_lock_timeout()
New
static os_int32 set_lock_timeout();Sets the time in milliseconds for which the current process will wait to acquire a lock. The time is rounded up to the nearest whole number of seconds. A value of -1 indicates that the process waits forever if necessary. The specified value applies to both read-locks and write-locks.
After an attempt is made to acquire a lock, if the specified time elapses without the lock's becoming available, an os_lock_timeout exception is signaled. If the attempt causes a deadlock, the transaction is aborted regardless of the specified timeout value.
For information about retrieving the timeout value, see objectstore::get_lock_timeout().
Note
set_lock_timeout() replaces the obsolete methods set_readlock_timeout() and set_writelock_timeout() that are defined by:
static void set_propagate_on_commit(
os_boolean when_to_propagate);
For use with ObjectStore/Single applications. Determines when ObjectStore propagates committed data from the transaction log to the affected database. If when_to_propagate is nonzero (true), propagations occur whenever a top level transaction commits. This is the default. If when_to_propagate is 0 (false), propagations occur when a database is closed and the program ends normally. If the program ends prematurely, some of the committed data in the log may not have been propagated to the database. This data will be propagated the next time ObjectStore is initialized or when objectstore::propagate_log() is called, provided that the correct transaction log exists at the time.
In client-server mode, propagation is controlled by server parameters, and set_propagate_on_commit() has no effect.
For information about retrieving when propagations occur, see objectstore::get_propagate_on_commit(). For additional information about the log file, see
objectstore::set_transaction_max_retries()
New
static void set_transaction_max_retries( os_unsigned_int32 max_retries );Sets the number of times a lexical transaction is automatically retried after being aborted because of a deadlock. See also objectstore::get_transaction_max_retries().
This method is equivalent to os_transaction::set_max_retries(), which is obsolete and will be removed from the API in a future release.
objectstore::set_union_variant()
New
static void set_union_variant(
void *address,
const char *type_name,
os_unsigned_int16 variant
);
Indicates to ObjectStore the currently active member object of a union in persistent memory. The arguments have the following meanings:
os_anonymous_indirect_type
os_anonymous_indirect_type::set_const()
Removed
Not supported; replaced by os_anonymous_indirect_type::set_is_const(). os_anonymous_indirect_type::set_volatile()
Removed
Not supported; replaced by os_anonymous_indirect_type::set_is_volatile(). os_array_type
os_array_type::number_of_elements()
Removed
Not supported; replaced by os_array_type::get_number_of_elements(). os_class_type
os_class_type::find_member()
Removed
Not supported; replaced by os_class_type::find_member_variable(). os_close_database
The os_close_database class enables you to close a database when a function ends, even if an exception causes it to end. To use this class, declare an automatic variable of the class os_close_database, giving its constructor a pointer to the os_database object that represents the database - usually, the pointer returned by os_database::open(). When the variable goes out of scope, its destructor calls os_database::close(). If the open count reaches 0, the database is closed; otherwise, it remains open for use by other parts of the application.
Every segment is created with an initial cluster, which is also the initial default cluster. New objects allocated using the os_segment or os_database overload of operator new are allocated to the appropriate default cluster. More clusters can be added by the application at any time. The application can also change the default cluster for the duration of the current session.
For more information about the os_cluster class, see Clusters.
A new class, os_cluster_cursor, has also been added to the segment API for iterating over clusters in a segment; see os_cluster_cursor.
Type definitions
The types os_int32 and os_boolean, used throughout this document, are each defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as an unsigned 32-bit integer type. Required header files
All ObjectStore programs must include the header file <ostore/ostore.hh>. os_cluster::database_of()
os_database *database_of() const;Returns a pointer to the database in which the specified cluster resides. The transient database is returned if the transient cluster is specified.
void destroy();Deletes the persistent cluster for which the function is called. When a cluster is destroyed, all data it contains is permanently destroyed, and pointers into the cluster become invalid. Any subsequent use of the destroyed cluster (such as an attempt to allocate memory within it) is an error.
os_allocation_strategy get_allocation_strategy(void) const;Returns the current strategy to use when allocating storage for an object in the specified cluster. For information about the return values, see objectstore::os_allocation_strategy_least_space and objectstore::os_allocation_strategy_least_wait. See also os_cluster::set_allocation_strategy().
os_cluster::get_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_segment,
os_fetch_stream,
os_fetch_cluster
};
void get_fetch_policy(
os_fetch_policy &policy,
os_int32 &bytes
) const;
Retrieves the cluster's current fetch policy. An enumerator of type os_fetch_policy is returned in policy and the fetch quantum is returned in bytes. For more information about the arguments and setting the fetch policy, see os_cluster::set_fetch_policy(). enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for the specified cluster. For information about the return value and about setting the lock option, see os_cluster::set_lock_option().
os_cluster::get_null_illegal_pointers()
os_boolean get_null_illegal_pointers() const;If the specified cluster is in null_illegal_pointers mode, the function returns nonzero (true); otherwise, it returns 0 (false). See os_cluster::set_null_illegal_pointers().
os_unsigned_int32 get_number() const;Returns the cluster number of the specified cluster. This number is suitable for passing to the method os_segment::get_cluster(); see os_segment::get_cluster().
os_cluster::get_transient_cluster()
static os_cluster *const get_transient_cluster();Returns a pointer to the transient cluster, which can be used as the argument to new() to cause allocation of transient memory.
os_boolean is_deleted();Returns nonzero (true) if the specified os_cluster has been deleted, and 0 (false) otherwise.
os_boolean is_empty();Returns nonzero (true) if the specified os_cluster contains no nondeleted objects, and 0 (false) otherwise.
os_boolean is_transient_cluster() const;Returns nonzero (true) if the specified cluster is transient, 0 (false) if persistent.
static os_cluster* of(void const* obj);Returns a pointer to the cluster in which the specified object resides. If the specified void* is 0 or points to transient memory, a pointer to the transient cluster is returned.
See os_cluster::get_transient_cluster().
void release_pointer();Releases the pointer specified by the this argument.
When an application calls a method that returns an os_cluster pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use.
When the application calls release_pointer(), ObjectStore decrements the use count for an ObjectStore object. When the last pointer is released, the count reaches 0, and the os_cluster object is deleted.
See the following for related information:
void retain_pointer();Retains the pointer specified by the this argument.
When an application calls a method that returns an os_cluster pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use. The application calls os_cluster::release_pointer() when it no longer needs the pointer, thus releasing it and decrementing the use count.
When the application calls retain_pointer(), ObjectStore increments the use count for an os_cluster object. Calling retain_pointer() ensures that the pointer is retained even when another part of the application releases it.
For information about using retain_pointer(), see C++ API User Guide. See also os_cluster::release_pointer().
void os_unsigned_int32 return_memory(os_boolean evict_now);Just like objectstore::return_memory(), except that it acts on a specified cluster rather than a specified range of addresses.
os_segment *segment_of() const;Returns a pointer to the segment in which the specified cluster resides. The transient segment is returned if the transient cluster is specified.
os_session *session_of() const;Returns the os_session object for the session in which the specified os_cluster* was retrieved.
This method can be used together with os_session::set_current() to enable a thread to join the session associated with an os_cluster object. For example, if cluster_ptr references an os_cluster object, then the statement
os_session::set_current(cluster_ptr->session_of());enables the currently executing thread to access the object by setting the thread's current session to the session associated with cluster_ptr.
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
void set_allocation_strategy( os_allocation_strategy );
Sets the strategy to use when looking for space to allocate for an object in the specified cluster. This strategy can be overridden by subsequent calls to
os_cluster::set_fetch_policy()
enum os_fetch_policy { os_fetch_cluster, os_fetch_segment,
os_fetch_page, os_fetch_stream };
void set_fetch_policy(os_fetch_policy policy, os_int32 bytes) const;
Sets the fetch policy for the specified cluster. The policy argument can be one of the following enumerators: os_fetch_cluster, os_fetch_segment, os_fetch_page, os_fetch_stream. The default fetch policy is os_fetch_page, with a fetch quantum of one page (see below). If an operation manipulates a substantial portion of a small cluster, use the os_fetch_cluster policy when performing the operation on the cluster. Under this policy, ObjectStore attempts to fetch the entire cluster containing the desired page in a single client/Server interaction, if the cluster will fit in the client cache without evicting any other data. If there is not enough space in the cache to hold the entire cluster, the behavior is the same as for os_fetch_page with a fetch quantum specified by bytes.
If an operation uses a cluster larger than the client cache, or does not refer to a significant portion of the cluster, use the os_fetch_page policy when performing the operation on the cluster. This policy causes ObjectStore to fetch a specified number of bytes at a time, rounded up to the nearest positive number of pages, beginning with the page required to resolve a given object reference. bytes specifies the fetch quantum. (Note that if you specify zero bytes, this will be rounded up, and the unit of transfer will be a single page.)
The default value for the fetch quantum depends on the default page size of the machine. Appropriate values might range from 4 KB to 256 KB or higher, depending on the size and locality of the application data structures.
For special operations that scan sequentially through very large data structures, os_fetch_stream might considerably improve performance. As with os_fetch_page, this fetch policy lets you specify the amount of data to fetch in each client/Server interaction for a particular cluster. But, in addition, it specifies that a double buffering policy should be used to stream data from the cluster.
This means that after the first two transfers from the cluster, each transfer from the cluster replaces the data cached by the second-to-last transfer from that cluster. This way, the last two chunks of data retrieved from the cluster will generally be in the client cache at the same time. And, after the first two transfers, transfers from the cluster generally will not result in eviction of data from other clusters. This policy also greatly reduces the internal overhead of finding pages to evict.
When you perform allocation that extends a cluster whose fetch policy is os_fetch_stream, the double buffering described above begins when allocation reaches an offset in the cluster that is aligned with the fetch quantum (that is, when the offset mod the fetch quantum is 0).
For all policies, if the fetch quantum exceeds the amount of available cache space (cache size minus wired pages), transfers are performed a page at a time. In general, the fetch quantum should be less than half the size of the client cache.
Note that a fetch policy established with set_fetch_policy() (for either a cluster or a segment) remains in effect only until the end of the process making the function call. Moreover, set_fetch_policy() only affects transfers made by this process. Other concurrent processes can use a different fetch policy for the same cluster or segment.
See os_cluster::get_fetch_policy().
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
void set_lock_option( objectstore_lock_option );
Sets the locking behavior for the specified cluster. objectstore_lock_option is an enumeration type whose enumerators specify the locking options:
os_boolean set_null_illegal_pointers();By default, ObjectStore signals a run-time error when it detects an illegal pointer. If you pass nonzero (true) to this function, ObjectStore changes the illegal pointer to 0 (null). You can specify the default behavior by passing 0 (false) to this function. The results of using this function do not remain in effect after the current process ends, and they are invisible to other processes. See also os_cluster::get_null_illegal_pointers().
os_unsigned_int32 size(os_boolean b_lock_cluster = 1);Returns the size in bytes of the specified cluster. If b_lock_cluster is nonzero (true, the default), the function waits until the specified cluster is read-locked before returning its size. If b_lock_cluster is 0 (false), the function returns the cluster's size without waiting. The reported size is transaction consistent if the cluster is locked.
static os_cluster_with with(const void* object);Returns a pointer to an os_cluster_with object. This return value can be used as the first argument to persistent new when allocating storage that is as close as possible to object.
For more information, see os_cluster_with.
os_cluster_cursor
New
Instances of the class os_cluster_cursor can be used to iterate over clusters in a segment. Type definitions
The types os_int32 and os_boolean, used throughout this document, are each defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as an unsigned 32-bit integer type. Required header files
All ObjectStore programs must include the header file <ostore/ostore.hh>. os_cluster_cursor::os_cluster_cursor()
os_cluster_cursor(
const os_segment *seg,
os_unsigned_int32 max_n_clusters_at_a_time = 100
);
Constructs an instance of os_cluster_cursor for iterating over the clusters in seg. max_n_clusters_at_a_time sets the number of clusters that can be maintained on the client at one time without having to return to the Server for another group. The constructor allocates a buffer large enough to hold the clusters. After constructing os_cluster_cursor, call os_cluster_cursor::next() to position os_cluster_cursor at the first cluster in the segment.
os_cluster *get_current() const;If os_cluster_cursor is positioned at a cluster, returns a pointer to that cluster. If os_cluster_cursor is not positioned at a cluster, it returns NULL. To position os_cluster_cursor at a cluster, call os_cluster_cursor::next().
os_cluster *next();Advances to the next cluster and returns a pointer to that cluster. If next() is called immediately after os_cluster_cursor is created, it positions os_cluster_cursor at the first cluster in the segment and returns a pointer to that cluster. If next() advances beyond the last cluster in the segment, it returns NULL.
void reset(); void reset(os_unsigned_int32 cluster_num); void reset(const os_segment *seg);Changes the os_cluster_cursor object as follows:
a_class *obj2 = new(os_cluster::with(obj1), a_typespec) a_class;In contrast, the following overloading of new tries to allocate storage for obj2 in the same cluster as obj1, assuming that obj1 is in a_cluster.
a_class *obj2 = new(a_cluster, a_typespec) a_class;For more information, see os_cluster::with().
Required header files
All ObjectStore programs must include the header file <ostore/ostore.hh>. os_cluster_with::get()
const void* get() const;Returns a pointer to the object near which another object is to be allocated. This pointer is the argument to os_cluster::with().
Programs compiled under UNIX that use this function must be linked with liboscmp.a; Windows programs do not require a special library.
static void compact(
const char** dbs_to_compact,
os_pathname_and_segment_number** segs_to_compact = 0,
os_pathname_segment_cluster** clstrs_to_compact = 0,
const char** referencing_dbs = 0,
os_pathname_and_segment_number** referencing_segs = 0,
os_pathname_segment_cluster** referencing_clstrs = 0
);
Compacts all persistent data in the specified databases, segments, and clusters - including ObjectStore collections, indexes, and bound queries. compact() also reorganizes any collections that reference compacted data and correctly relocates pointers and ObjectStore references to compacted data.Following are the arguments to compact():
The set of segments to be compacted is the union of all segments in all databases specified by dbs_to_compact, plus those segments specified by segs_to_compact.
Likewise, the set of clusters to be compacted is the union of all clusters in all segments of all databases specified by dbs_to_compact, plus the clusters of those segments specified by segs_to_compact and those clusters specified by clstrs_to_compact.
If any of the compaction-specific arguments are invalid, err_os_compaction is signaled.
Protected references are unaffected by compaction and therefore need not be specified in any of the referencing arguments to compact(). For information about protected references, see os_Reference_protected<T>.
Restrictions
Note the following restrictions when calling compact():
The empty space left in clusters after compaction can be returned to the allocation pool for the host file, making the disk space allocated to the hole available to other clusters in the same database. However, since operating systems provide no mechanism to free disk space allocated to regions internal to the host file, any such free space is inaccessible to other databases stored in other host files. Compacting a file database does not reduce its size.
void affiliate(
os_database* target_db,
os_boolean deep = 0,
os_boolean relative = 1,
const char* common_parent = NULL
);
Invoking this function on the specified database causes target_db to become affiliated with the specified database and writes an entry in its pathname pool to the target database. You must call affiliate() once for each target database that will contain objects pointed to by objects in the specified database. The arguments have the following meanings:
For more information, see Affiliation and Cross-Database Pointers.
os_database::allow_external_pointers()
Removed
Not supported, replaced by the affiliation API; see os_database::affiliate().
os_database::change_affiliation()
New
void change_affiliation(os_unsigned_int16 index,
const os_database* target_db,
os_boolean relative = 1,
const char* common_parent = NULL
);
Replaces the path to an affiliated database with the path to target_db. This function is especially useful when making a copy of a database that is affiliated with another database, and you want to change the affiliation from the original database to its copy. Calling this function does not modify or validate the user's persistent pointers. The arguments have the following meanings:
void close(os_boolean force = 0);ObjectStore maintains an open count on every opened database. Calling open() on a database that is already open increments the count if the second call requests the same mode as used in the initial call. Calling close() decrements the open count. The database is closed when the count reaches 0.
close() now takes an optional argument, force. When this argument is set to nonzero (true), the database is closed regardless of its open count. The default is 0 (false): close the database only when close() decrements the open count to 0.
You can call close() inside or outside a transaction.
For information about opening a database and its effect on the open count, see os_database::open(). For information about using an automatic variable of the class os_close_database to close a database, see os_close_database.
os_database::create_segment()
Changed
The behavior of this method when it is invoked on a transient database has changed. Previous to Release 6.0, when this method was invoked on a transient database, it returned a pointer to the transient segment. Starting with this release, create_segment() returns the error err_database_transient. os_database::decache()
Removed
Not supported. The clean-up operations performed by this function are now handled by os_database::close() and os_database::destroy(). os_database::destroy()
Changed
The behavior of destroy() has changed. This method can be used only on a persistent database. Invoking destroy() on a transient database causes the err_database_transient exception. Use ::operator delete to delete a transient database. os_database::get_affiliated_databases()
New
void get_affiliated_databases(
os_int32 &n_databases,
os_database**& databases
) const;
Returns an array of pointers to the affiliated databases; that is, to all databases with entries in the pathname pool of the specified database. When the function returns, n_databases refers to the number of elements in the array. It is the user's responsibility to deallocate the array when it is no longer needed. This function replaces os_database::get_database_references().For more information, see Affiliation and Cross-Database Pointers.
os_database::get_affiliation_index_of()
New
os_unsigned_int16 get_affiliation_index_of(
const os_database* target_db) const;
Returns the index of the path to target_db in the pathname pool of this database. target_db must have been previously affiliated with this database. If it is not affiliated, get_affiliation_index_of() returns 0. The return value is useful when you want to change the affiliation of a database; see os_database::change_affiliation().
os_database::get_all_segments()
Changed
void get_all_segments(
os_int32 max_segments,
os_segment_p *segs,
os_int32& n_segments
) const;
This function has been changed to const.
void get_all_segments_and_permissions(
os_int32 max_segments,
os_segment_p *segs,
os_segment_access_p* controls,
os_int32& n_segments
) const;
This function has been changed to const.
os_allocation_strategy get_allocation_strategy(void) const;Returns the current strategy to use when allocating storage for an object in the specified database. For information about the return values, see objectstore::os_allocation_strategy_least_space and objectstore::os_allocation_strategy_least_wait. See also os_database::set_allocation_strategy().
os_database::get_database_references()
Removed
Not supported, replaced by the affiliation API; see os_database::get_affiliated_databases().
os_database::get_default_lock_whole_segment()
Removed
Not supported. os_database::get_default_null_illegal_pointers()
Removed
Not supported. os_database::get_default_segment()
Changed
os_segment *get_default_segment() const;This function has been changed to const.
void get_fetch_policy(os_fetch_policy &, os_int32 &) const;This function has been changed to const. For more information about the arguments, see os_cluster::set_fetch_policy(). For information about setting the fetch policy, see os_database::set_fetch_policy().
os_database::get_id()
Removed
Not supported; database IDs are no longer supported. os_database::get_incremental_schema_installation()
Changed
os_boolean get_incremental_schema_installation() const;This function has been changed to const.
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for the specified database, including all its segments and clusters. For more information about the return value, see os_cluster::set_lock_option(). For more information about setting the lock option, see os_database::set_lock_option().
os_database::get_lock_whole_segment()
Removed
Not supported; replaced by os_database::get_lock_option(). os_database::get_opt_cache_lock_mode()
Removed
Not supported. For more information, see objectstore::own_page_write.
os_database::get_path_to()
New
char* get_path_to(os_database* target_db) const;Returns a newly allocated string that contains the path from this database to target_db. Depending on how the affiliation was established, the path can be absolute or relative. The user must delete the string.
For more information, see Affiliation and Cross-Database Pointers.
os_database::get_relative_directory()
Removed
Not supported, replaced by the affiliation API; see os_database::get_path_to().
os_database::get_segments()
New
void get_segments(
os_unsigned_int32 first_seg_num,
os_unsigned_int32 max_segments,
os_segment_p *segs,
os_unsigned_int32 &n_segments,
os_boolean &b_more
) const;
Returns a maximum number of segments, as specified in max_segments. first_seg_num specifies the number of the first segment in the range. The segments are returned in segs, which must be allocated by the user. n_segments contains the number of segments actually returned, and b_more is true if there are more segments to retrieve. You can use get_segments() to write your own segment iterator, or you can use the iterator class os_segment_cursor; see os_segment_cursor.
os_database::has_affiliation_to()
New
os_boolean has_affiliation_to(const os_database* target_db) const;Returns nonzero (true) if target_db is affiliated with this database; otherwise, returns 0 (false). For information about retrieving a list of all the databases affiliated with a specific database, see os_database::get_affiliated_databases().
os_database::is_open_update()
New
os_boolean is_open_update() const;Returns nonzero (true) if the database for which the function is called is open for update, and 0 (false) otherwise.
os_boolean is_transient_database() const;Returns nonzero (true) if the specified database is transient, 0 (false) if it is persistent.
If an attempt is made to open a database that is already opened and the second call to open() specifies a different mode, err_db_cannot_change_open is signaled. See err_db_cannot_change_open.
See also os_database::close().
os_database::release_pointer()
New
void release_pointer();Releases the pointer specified by the this argument.
When an application calls a method that returns an os_database pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use.
When the application calls release_pointer(), ObjectStore decrements the use count for an ObjectStore object. When the last pointer is released, the count reaches 0, and the os_database object is deleted.
See the following for related information:
void retain_pointer();Retains the pointer specified by the this argument.
When an application calls a method that returns an os_database pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use. The application calls os_database::release_pointer() when it no longer needs the pointer, thus releasing it and decrementing the use count.
When the application calls retain_pointer(), ObjectStore increments the use count for an os_database object. Calling retain_pointer() ensures that the pointer is retained even when another part of the application releases it.
For information about using retain_pointer(), see C++ API User Guide. See also os_database::release_pointer().
os_database::return_memory()
New
void os_unsigned_int32 return_memory(os_boolean evict_now);Just like objectstore::return_memory(), except that it acts on a specified database rather than a range of addresses.
os_session *session_of() const;Returns the os_session object for the session in which the specified os_database* was retrieved.
This method can be used together with os_session::set_current() to enable a thread to join the session associated with an os_database object. If, for example, db_ptr references an os_database object, then the statement
os_session::set_current(db_ptr->session_of());enables the currently executing thread to access the object by setting the thread's current session to the session associated with db_ptr.
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
void set_allocation_strategy( os_allocation_strategy );
Sets the strategy to use when looking for space to allocate for an object in clusters in the specified database. This strategy applies to all segments and clusters in the database unless specifically overridden by a subsequent call to os_database::set_allocation_strategy() or to
os_database::set_default_null_illegal_pointers()
Removed
Not supported. os_database::set_default_lock_whole_segment()
Removed
Not supported. os_database::set_default_segment_size()
Removed
Not supported; segments cannot be presized. os_database::set_fetch_policy()
Changed
This method has been changed so that the fetch policy can be set for the specified database by setting the policy argument to os_fetch_cluster. The policy argument can also be one of the following: os_fetch_segment, os_fetch_page, os_fetch_stream. os_database::set_lock_option()
New
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
void set_lock_option(objectstore_lock_option);
Sets the locking behavior for the specified database, including all its segments and clusters. In all other respects, this method is the same as os_cluster::set_lock_option().
os_database::set_lock_whole_segment()
Removed
Not supported; replaced by os_database::set_lock_option(). os_database::set_new_id()
Removed
Not supported; database IDs are no longer supported. os_database::set_opt_cache_lock_mode()
Removed
Not supported. For more information, see objectstore::own_page_write.
os_database::set_relative_directory()
Removed
Not supported; replaced by os_database::affiliate(). os_database_reference
Removed
The os_database_reference class has been completely removed. Existing applications that call
os_database::get_database_references() os_database::change_database_references()must be changed to remove the calls. get_database_references() can be replaced with a call to os_database::get_affiliated_databases(); see os_database::get_affiliated_databases().
os_database_root
Changed
The following members of this class have changed:
void destroy();Destroys the persistent root of the database for which the function is called. Applications written for earlier releases of ObjectStore that used ::operator delete to delete the persistent root must be changed to use destroy() instead.
const char* get_name() const;This method and its return value are now const.
const os_typespec *get_typespec();This return value of this method is now const.
void release_pointer();Releases the pointer specified by the this argument.
When an application calls a method that returns an os_database_root pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use.
When the application calls release_pointer(), ObjectStore decrements the use count for an ObjectStore object. When the last pointer is released, the count reaches 0, and the os_database_root object is deleted.
See the following for related information:
void retain_pointer();Retains the pointer specified by the this argument.
When an application calls a method that returns an os_database_root pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use. The application calls os_database_root::release_pointer() when it no longer needs the pointer, thus releasing it and decrementing the use count.
When the application calls retain_pointer(), ObjectStore increments the use count for an os_database_root object. Calling retain_pointer() ensures that the pointer is retained even when another part of the application releases it.
For information about using retain_pointer(), see C++ API User Guide. See also os_database_root::release_pointer().
os_database_root::~os_database_root()
Changed
Starting with Release 6.0 of ObjectStore, the destructor deletes the transient os_database_root object. It does not delete the persistent database root or the associated name (persistent char *). os_dbutil
os_dbutil::osprmgc()
Removed
Not supported; PRM bloat is no longer an issue. See Relocation Optimization.
os_dbutil::osverifydb_one_segment()
Changed
static os_unsigned_int32 osverifydb_one_segment(
const char *dbname,
os_unsigned_int32 segment_number,
os_unsigned_int32 cluster_start_number = 0,
os_unsigned_int32 cluster_end_number = 0,
os_unsigned_int32 starting_offset = 0,
os_unsigned_int32 ending_offset = 0,
os_verifydb_options *opt = 0
);
The osverifydb_one_segment() method has been changed to accept two additional arguments:
The meaning of the remaining arguments has not changed.
Type definitions
The types os_int32 and os_boolean, used throughout this manual, are each defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as an unsigned 32-bit integer type. Required header file
All ObjectStore programs must include the header file <ostore/ostore.hh>. os_int64::os_int64()
os_int64(os_int64 num);Constructs a copy of num.
os_int64(os_platform_int64 num);Constructs an instance of os_int64 based on the value of num. os_platform_int64 is an ObjectStore type definition for native 64-bit integer data types, if there is one.
os_int64(os_int32 num);Constructs an instance of os_int64 based on the value of num, a 32-bit integer.
os_int64(os_int32 high, os_int32 low);Constructs an instance of os_int64 based on the values of high and low, where high represents the upper 32 bits and low represents the lower 32 bits.
os_int32 get_low( );Returns a 32-bit integer, based on the upper 32 bits of the value of the object.
os_int32 get_low( );Returns a 32-bit integer, based on the lower 32 bits of the value of the object.
void sprint(char *result, os_int32 = 10) const;Converts the value of the object into a formatted string at the specified base and writes the string to result. base can be either 10 or 16; the default is 10.
static void os_notification::subscribe( const os_cluster *clstr ); static void os_notification::unsubscribe( const os_cluster *clstr );They are otherwise the same as in the previous release. For more information, see the C++ API Reference.
os_object_cursor
os_object_cursor::os_object_cursor()
Changed
os_object_cursor::os_object_cursor(const os_cluster *cluster);Creates a new os_object_cursor associated with the specified cluster. If the cluster is empty, the cursor is positioned at no object; otherwise, it is positioned at the first object in the cursor's associated cluster. The object is first in an arbitrary order that is stable across traversals of the cluster, as long as no objects are created or deleted from the cluster, and no reorganization is performed (using schema evolution or compaction).
void reset(const void *ptr);Moves the cursor to the object at the address ptr. If ptr points to deleted space, the cursor is positioned at the object immediately after that address. If there is no object after the deleted space, err_cursor_not_at_object is signaled.
Required header file
Programs using this function must include <ostore/compact.hh>. os_pathname_segment_cluster::database_pathname
const char *database_pathname;The value of this member is the pathname of the database containing the segment identified by the os_pathname_segment_cluster object.
os_pathname_segment_cluster(
const char *db,
os_unsigned_int32 seg_number
os_unsigned_int32 clstr_number
);
The constructor takes three arguments:
os_unsigned_int32 cluster_number;The value of this member is the number of the cluster identified by the os_pathname_segment_cluster object. For information about obtaining the number of a cluster, see os_cluster::get_number().
os_pathname_segment_cluster::segment_number
os_unsigned_int32 segment_number;The value of this member is the number of the segment identified by the os_pathname_segment_cluster object. For information about obtaining the number of a segment, see os_segment::get_number().
Following are the members of the os_pvar class, all of which have been removed from the ObjectStore API:
char* dump( ) const; char* dump( const char* db_str ) const;The format of the dump string returned by this function has changed to support clusters; see Clusters. User applications that rely on the undocumented format of the dump string will have to be changed.
void dump( const char* dump_str ) const; void dump( const char* dump_str, const os_database* db ) const;The format of the dump string has changed to support clusters; see Clusters. User applications that rely on the undocumented format of the dump string will have to be changed.
os_release_cluster_pointer
New
The os_release_cluster_pointer class enables you to release pointers to objects of the class os_cluster. To do so, declare an automatic variable of the class os_release_cluster_pointer, giving its constructor a pointer to an os_cluster object. When the variable goes out of scope, its destructor releases the pointer.
os_release_database_pointer
New
The os_release_database_pointer class enables you to release pointers to objects of the class os_database. To do so, declare an automatic variable of the class os_release_database_pointer, giving its constructor a pointer to an os_database object. When the variable goes out of scope, its destructor releases the pointer.
os_release_root_pointer
New
The os_release_root_pointer class enables you to release pointers to objects of the class os_database_root. To do so, declare an automatic variable of the class os_release_root_pointer, giving its constructor a pointer to an os_database_root object. When the variable goes out of scope, its destructor releases the pointer.
os_release_segment_pointer
New
The os_release_segment_pointer class enables you to release pointers to objects of the class os_segment. To do so, declare an automatic variable of the class os_release_segment_pointer, giving its constructor a pointer to an os_segment object. When the variable goes out of scope, its destructor releases the pointer.
os_segment
Changed
The following members of this class have changed:
os_segment::allow_external_pointers()
Removed
Not supported, replaced by the affiliation API; see os_database::affiliate().
os_segment::create_cluster()
New
os_cluster* os_segment::create_cluster();Creates a cluster in the specified segment, and returns a pointer to an instance of the class os_cluster (see os_cluster). Call this function within a transaction. The return value points to a transient object representing the new cluster. Note that, since it points to transient memory, the return value of this function cannot be stored persistently. This function returns an error (err_segment_transient) if invoked on a transient database; see err_segment_transient.
This function replaces os_segment::create_object_cluster().
os_segment::create_object_cluster()
Removed
Not supported. The os_object_cluster has been removed from the API; see Clusters for more information.
os_segment::external_pointer_status()
Removed
Not supported; replaced by os_database::affiliate(). os_segment::get_all_clusters()
New
void get_all_clusters(
os_int32 max_clusters,
os_cluster_p* cluster_array,
os_int32& max_to_return
) const;
Provides access to all the clusters in the specified segment. os_cluster_p* is an array of pointers to segments. This array must be allocated by the user. The function os_segment::get_n_clusters() can be used to determine how large an array to allocate; see os_segment::get_n_clusters(). max_clusters specifies the maximum number of elements the array is to have. n_returned refers to the actual number of segment pointers returned.
This function replaces os_segment::get_all_object_clusters().
os_segment::get_allocation_strategy()
New
os_allocation_strategy get_allocation_strategy( void ) const;Returns the current strategy to use when allocating storage for an object in the specified segment. For information about the return values, see objectstore::os_allocation_strategy_least_space and objectstore::os_allocation_strategy_least_wait. See also os_segment::set_allocation_strategy().
os_segment::get_all_object_clusters()
Removed
Not supported. The os_object_cluster has been removed from the API; see Clusters for more information.
os_cluster *get_cluster(os_unsigned_int32 cluster_num) const;Returns a pointer to the cluster in the specified segment with the specified cluster number. See os_cluster::get_number().
os_segment::get_clusters()
New
void get_clusters(
os_unsigned_int32 first_cluster_num,
os_unsigned_int32 max_clusters,
os_cluster_p *clusters,
os_unsigned_int32& n_clusters,
os_boolean &b_more
) const;
Returns a maximum number of clusters, as specified in max_clusters. first_cluster_num specifies the number of the first cluster in the range. The clusters are returned in clusters, which must be allocated by the user. n_clusters contains the number of clusters actually returned, and b_more is true if there are more clusters to retrieve. You can use get_clusters() to write your own cluster iterator, or you can use the ObjectStore iterator class; see os_cluster_cursor.
os_segment::get_comment()
Changed
char* get_comment() const;This method has been changed to const.
os_segment::get_default_cluster()
New
os_cluster *get_default_cluster() const;Returns a pointer to the default cluster of the specified segment. The default cluster is the cluster in which persistent memory is allocated by default when new is called with only an os_segment* argument. A session can change the default at any time (see os_segment::set_default_cluster()), but the change remains in effect only for the duration of the session, and is invisible to other sessions.
Simple ObjectStore applications need not create any clusters; all the segment's persistent data can be stored in the initial cluster, subject to size limitations. But if more sophisticated clustering is required, the application can create new clusters in the database, and it might be convenient to make one of these the default.
os_segment::get_fetch_policy()
Changed
void get_fetch_policy(os_fetch_policy &, os_int32 &) const;This function has been changed to const. For more information about the arguments, see os_cluster::set_fetch_policy(). For information about setting the fetch policy, see os_segment::set_fetch_policy().
os_segment::get_lock_option()
New
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for the specified segment. For more information about the return value, see os_cluster::set_lock_option(). For more information about setting the lock option, see os_segment::set_lock_option().
os_segment::get_lock_whole_segment()
Removed
Not supported; replaced by os_segment::get_lock_option(). os_segment::get_n_clusters()
New
os_int32 get_n_clusters() const;Returns the number of clusters in the specified segment. This function replaces os_segment::get_n_object_clusters().
os_boolean is_empty();This function is no longer const.
os_boolean is_transient_segment() const;Returns nonzero (true) if the specified segment is transient, 0 (false) if persistent.
void release_pointer();Releases the pointer specified by the this argument.
When an application calls a method that returns an os_segment pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use.
When the application calls release_pointer(), ObjectStore decrements the use count for an ObjectStore object. When the last pointer is released, the count reaches 0, and the os_segment object is deleted.
See the following for related information:
void retain_pointer();Retains the pointer specified by the this argument.
When an application calls a method that returns an os_segment pointer, ObjectStore increments a use count of the number of times it has returned a pointer to the same object. The use count thus represents the number of pointers to the same object that are currently in use. The application calls os_segment::release_pointer() when it no longer needs the pointer, thus releasing it and decrementing the use count.
When the application calls retain_pointer(), ObjectStore increments the use count for an os_segment object. Calling retain_pointer() ensures that the pointer is retained even when another part of the application releases it.
For information about using retain_pointer(), see C++ API User Guide. See also os_segment::release_pointer().
os_segment::return_memory()
Changed
void os_unsigned_int32 return_memory(os_boolean evict_now);The return type of this function has been changed to void.
os_session *session_of() const;Returns the os_session object for the session in which the specified os_segment* was retrieved.
This method can be used together with os_session::set_current() to enable a thread to join the session associated with an os_segment object. For example, if seg_ptr references an os_segment object, then the statement
os_session::set_current(seg_ptr->session_of());enables the currently executing thread to access the object by setting the thread's current session to the session associated with seg_ptr.
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
void set_allocation_strategy( os_allocation_strategy );
Sets the strategy to use when looking for space to allocate for an object in clusters in the specified segment. This strategy can be overridden by subsequent calls to
os_segment::set_comment()
Changed
void set_comment(const char *info);In previous releases, info was a char * and was limited to 31 characters. In Release 6.0, it has been changed to a const char *, and there is no practical limit on the length of the string it points to.
void set_default_cluster(os_cluster* cluster);Sets the default cluster for the specified segment. The default cluster is the cluster in which persistent memory is allocated by default when new is called with only an os_segment* or os_database* argument. Changing the default cluster remains in effect only for the duration of the process, and is invisible to other processes.
Simple ObjectStore applications need not create any clusters; all the segment's persistent data can be stored in the initial cluster, subject to size limitations. But if more sophisticated clustering is required, the application can create new clusters in the database, and it might be convenient to make one of these the default.
enum os_fetch_policy { os_fetch_cluster, os_fetch_segment,
os_fetch_page, os_fetch_stream };
void set_fetch_policy(os_fetch_policy policy, os_int32 bytes) const;
This method has been changed to allow the policy argument to be set to os_fetch_cluster. The policy argument can also be one of the following: os_fetch_segment, os_fetch_page, os_fetch_stream. If an operation manipulates a substantial portion of a small cluster, use the os_fetch_cluster policy when performing the operation on a segment. Under this policy, ObjectStore attempts to fetch the entire cluster containing the desired page in a single client/Server interaction, if the cluster will fit in the client cache without evicting any other data. If there is not enough space in the cache to hold the entire cluster, the behavior is the same as for os_fetch_page with a fetch quantum specified by bytes.
enum objectstore_lock_option {
lock_as_used,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
void set_lock_option(objectstore_lock_option);
Sets the locking behavior for the specified segment, including all clusters in the segment. In all other respects, this method is the same as os_cluster::set_lock_option().
os_segment::set_lock_whole_segment()
Removed
Not supported; replaced by os_segment::set_lock_option(). os_segment::set_read_whole_segment()
Removed
Not supported; replaced by os_segment::set_fetch_policy(). os_segment::set_size()
Removed
Not supported; segments cannot be presized. os_segment::size()
Changed
os_unsigned_int64 size(os_boolean b_lock_segment = 1);This function has changed:
os_segment_cursor(
const os_database *db,
os_unsigned_int32 max_n_segments_at_a_time = 100
);
Constructs an instance of os_segment_cursor for iterating over the segments in db. max_n_segments_at_a_time sets the number of segments that can be maintained on the client at one time without having to return to the Server for another group. The constructor allocates a buffer large enough to hold the segments. After constructing os_segment_cursor, call os_segment_cursor::next() to position os_segment_cursor at the first cluster in the segment.
os_segment *get_current() const;If os_segment_cursor is positioned at a segment, returns a pointer to that segment. If os_segment_cursor is not positioned at a segment, it returns NULL. To position os_segment_cursor at a segment, call os_segment_cursor::next().
os_segment *next();Advances to the next segment and returns a pointer to that segment. If next() is called immediately after os_segment_cursor is created, it positions os_segment_cursor at the first segment in the database and returns a pointer to that segment. If next() advances beyond the last segment in the database, it returns NULL.
void reset(); void reset(os_unsigned_int32 segment_num); void reset(const os_database *db);Changes the os_segment_cursor object as follows:
virtual void get_databases(
os_int32 max_to_return,
os_database_p* dblist,
os_int32 &count
) const = 0;
virtual os_int32 get_n_databases() const = 0;
virtual os_boolean connection_is_broken() const = 0;
os_subscription
Changed
The following methods of the class os_subscription have been overloaded with os_cluster, replacing the os_object_cluster overloadings:
os_subscription( const os_cluster* clstr ); void assign( const os_cluster* clstr ); os_subscription &operator=( const os_cluster* clstr );These methods are otherwise the same as in the previous release. For more information, see the C++ API Reference.
os_transaction::begin()
Changed
os_transaction::begin() does not support the parent argument. This argument is redundant. The following overloadings of os_transaction::begin() are supported:
static os_transaction *os_transaction::begin(
transaction_type_enum t_type = os_transaction::update,
transaction_scope_enum t_scope = os_transaction::local
);
static os_transaction *os_transaction::begin(
char *name,
transaction_type_enum t_type = os_transaction::update,
transaction_scope_enum t_scope = os_transaction::local
);
Note that this release, like the previous release, supports both local (os_transaction::local) and global (os_transaction::global) transactions. By default, all transactions are global.
os_transaction::is_lock_contention()
New
static os_boolean is_lock_contention();Returns nonzero (true) if a Server involved in the specified transaction has experienced contention for some persistent memory that the calling application is using; otherwise, returns 0 (false). It also returns false if not called from within a transaction.
This function can be used in conjunction with MVCC to help determine whether to start a new transaction in order to make available more up-to-date data. is_lock_contention() returns nonzero (true) if your application has a database open for MVCC, and during the current transaction. another application has write-locked a page read by your application.
Calling this function outside a transaction signals err_trans.
This function is advisory only; it does not have to be called, and you can ignore its return value without jeopardizing in any way the correctness of ObjectStore's behavior.
os_transaction::is_prepare_to_commit_invoked()
Removed
Not supported; replaced by os_transaction::is_prepared().
os_transaction::is_prepared()
New
Returns nonzero (true) if os_transaction::prepare_to_commit() was called in the current transaction, and 0 (false) otherwise. os_transaction::session_of()
New
os_session *session_of() const;Returns the os_session object for the session in which the specified os_transaction* was retrieved.
This method can be used together with os_session::set_current() to enable a thread to join the session associated with an os_transaction object. For example, if txn_ptr references an os_transaction object, then the statement
os_session::set_current(txn_ptr->session_of());enables the currently executing thread to access the object by setting the thread's current session to the session associated with txn_ptr.
static os_typespec *get_os_int16();Returns a pointer to a typespec for the ObjectStore portable type os_int16. The first time such a function is called by a particular process, it will allocate the typespec and return a pointer to it. Subsequent calls to the function in the same process do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_int32();Returns a pointer to a typespec for the ObjectStore portable type os_int32. The first time such a function is called by a particular process, it will allocate the typespec and return a pointer to it. Subsequent calls to the function in the same process do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_int64();Returns a pointer to a typespec for the ObjectStore portable type os_int64. The first time such a function is called by a particular session, it allocates the typespec and returns a pointer to it. Subsequent calls to the function in the same session do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_signed_int8();Returns a pointer to a typespec for the ObjectStore portable type os_signed_int8. The first time such a function is called by a particular process, it will allocate the typespec and return a pointer to it. Subsequent calls to the function in the same process do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_unsigned_int8();Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_int8. The first time such a function is called by a particular process, it will allocate the typespec and return a pointer to it. Subsequent calls to the function in the same process do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_unsigned_int16();Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_int16. The first time such a function is called by a particular process, it will allocate the typespec and return a pointer to it. Subsequent calls to the function in the same process do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_unsigned_int32();Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_int32. The first time such a function is called by a particular process, it will allocate the typespec and return a pointer to it. Subsequent calls to the function in the same process do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
static os_typespec *get_os_unsigned_int64();Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_int64. The first time such a function is called by a particular session, it allocates the typespec and returns a pointer to it. Subsequent calls to the function in the same session do not result in further allocation; instead, a pointer to the same os_typespec object is returned.
Type definitions
The types os_int32 and os_boolean, used throughout this manual, are each defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as an unsigned 32-bit integer type. Required header file
All ObjectStore programs must include the header file <ostore/ostore.hh>. os_unsigned_int64::os_unsigned_int64()
os_unsigned_int64(os_unsigned_int64 num);Constructs a copy of num.
os_unsigned_int64(os_platform_int64 num);Constructs an instance of os_unsigned_int64 based on the value of num. os_platform_int64 is an ObjectStore type definition for native 64-bit integer data types, if there is one.
os_unsigned_int64(os_unsigned_int32 num);Constructs an instance of os_unsigned_int64 based on the value of num, a 32-bit integer.
os_unsigned_int64(os_unsigned_int32 high,
os_unsigned_int32 low);
Constructs an instance of os_unsigned_int64 based on the values of high and low, where high represents the upper 32 bits and low represents the lower 32 bits.
os_unsigned_int32 get_low( );Returns an unsigned 32-bit integer, based on the upper 32 bits of the value of the object.
os_unsigned_int32 get_low( );Returns an unsigned 32-bit integer, based on the lower 32 bits of the value of the object.
void sprint(char *result, os_int32 = 10) const;Converts the value of the object into a formatted string at the specified base and writes the string to result. base can be either 10 or 16; the default is 10.
err_default_cluster
New
Cluster cannot be assigned as the default cluster. It can be a huge cluster, or it might not be in the specified segment. err_default_segment
New
Segment cannot be assigned as the default segment. It can be the system segment, or it might not be in the specified database. err_destroy_cluster_not_empty
Removed
This exception has been removed. The os_object_cluster class is no longer supported; see os_object_cluster.
err_opened_read_only
Removed
This exception has been renamed err_database_not_open_update. The meaning of the exception has not changed; the new name is more accurate. err_pvar_init_failure
Removed
This exception has been removed. The os_pvar class is no longer supported; see os_pvar.
err_pvar_type_mismatch
Removed
This exception has been removed. The os_pvar class is no longer supported; see os_pvar.
err_segment_transient
New
Signaled when the user attempts to perform an operation that is not legal for transient segments. For example, this error is signaled if you attempt to create a cluster in a transient segment; see os_segment::create_cluster().
err_typespec_mismatch
New
Signaled when typespecs do not match. For example, if the typespec passed to os_database_root::get_value() does not match the typespec passed to os_database_root::set_value(), this exception is signaled.
Updated: 03/11/99 12:17:35