os_segment

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.

All ObjectStore programs must include the header file <ostore/ostore.hh>.

os_segment::allow_external_pointers()

void allow_external_pointers();

At any given time, a pointer from one database, db1, to another, db2, points to whichever database has a certain pathname - namely, db2's pathname at the time the pointer was stored. If db2's pathname changes (for example, as a result of performing osmv on db2), the pointer will no longer refer to data in db2. If some other database, db3, is given db2's original pathname (for example, as a result of performing osmv on db3), the pointer will refer to data in db3.

The pathname is not stored as part of the cross-database pointer (which takes the form of a regular virtual memory address), but rather as part of an os_database_reference stored in a table associated with the pointer.

It is illegal to rename a database so that a pointer that used to refer to another database now refers to the database in which the pointer itself resides.

os_database_references normally store a relative pathname. That is, if the source and destination databases have a common ancestor directory, the common directory is not stored as part of the pathname - only the part of the target database's pathname that is not shared with the source database's pathname is stored. The common part of the pathname is preceded by the appropriate number of ../s to traverse the hierarchy up from the source directory to the common ancestor directory. For example, if the source and target databases are named /sys/appl/mydb and /sys/lib/lib1, respectively, the reference will store the relative pathname, ../lib/lib1.

You can override use of relative pathnames with the functions os_database::set_relative_directory() and os_database::get_relative_directory() - see the entries for these functions.

Dereferencing a cross-database pointer causes the destination database, if not already open, to be opened for read/write. Thus, dereferencing such a pointer can result in error messages such as database not found.

os_segment::create_object_cluster()

os_object_cluster *create_object_cluster(os_unsigned_int32 size);

os_segment::database_of()

os_database *database_of();

os_segment::destroy()

void destroy();

os_segment::external_pointer_status()

void external_pointer_status(os_int32 *allowed, os_int32 *exist);

os_segment::get_access_control()

os_segment_access *get_access_control() const;

os_segment::get_all_object_clusters()

void get_all_object_clusters(
      os_int32 max_to_return, 
      os_object_cluster_p *cluster_array, 
      os_int32 &n_returned)
) const;

os_segment::get_application_info()

void *get_application_info() const;

os_segment::get_check_illegal_pointers()

os_boolean get_check_illegal_pointers() const;

os_segment::get_comment()

char *get_comment() const;

os_segment::get_database_references()

void get_database_references(
      os_int32 &n_refs, 
      os_database_reference_p *&array
) const;

os_segment::get_fetch_policy()

void get_fetch_policy(os_fetch_policy &policy, os_int32 &bytes);

os_segment::get_lock_whole_segment()

objectstore_lock_option get_lock_whole_segment();

os_segment::get_n_object_clusters()

os_int32 get_n_object_clusters();

os_segment::get_null_illegal_pointers()

os_boolean get_null_illegal_pointers();

os_segment::get_number()

os_unsigned_int32 get_number() const;

os_segment::get_readlock_timeout()

os_int32 get_readlock_timeout() const;

os_segment::get_writelock_timeout()

os_int32 get_writelock_timeout() const;

os_segment::get_transient_segment()

static os_segment *const get_transient_segment();

os_segment::is_deleted()

os_boolean is_deleted();

os_segment::is_empty()

os_boolean is_empty() const;

os_segment::lock_into_cache()

void lock_into_cache();

os_segment::of()

static os_segment *of(void *location);

os_segment::return_memory()

os_unsigned_int32 return_memory(os_boolean evict_now);

os_segment::set_access_control()

void set_access_control(const os_segment_access *new_access);

os_segment::set_application_info()

void set_application_info(void *info);

os_segment::set_check_illegal_pointers()

void set_check_illegal_pointers(os_boolean);

By default, ObjectStore sometimes checks for illegal pointers, but other times the checking is optimized out. However, you can instruct ObjectStore always to check for illegal pointers in a given segment or database on transaction commit.

If you pass 1 (true) to set_check_illegal_pointers(), check_illegal_pointers mode is enabled for the specified segment. Upon commit of each transaction, for each segment in check_illegal_pointers mode, ObjectStore always checks each page used in the transaction. You can specify the default behavior by passing 0 (false).

The results of using this function do not remain in effect after the current process ends, and are invisible to other processes.

os_segment::set_comment()

void set_comment(char *info);

os_segment::set_fetch_policy()

enum os_fetch_policy { os_fetch_segment, os_fetch_page, os_
fetch_stream } ;
void set_fetch_policy(os_fetch_policy policy, os_int32 bytes);

The default fetch policy is os_fetch_page, with a fetch quantum of 1 page (see below).

If an operation manipulates a substantial portion of a small segment, use the os_fetch_segment policy when performing the operation on the segment. Under this policy, ObjectStore attempts to fetch the entire segment containing the desired page in a single client/server interaction, if the segment will fit in the client cache without evicting any other data. If there is not enough space in the cache to hold the entire segment, the behavior is the same as for os_fetch_page with a fetch quantum specified by bytes.

If an operation uses a segment larger than the client cache, or does not refer to a significant portion of the segment, use the os_fetch_page policy when performing the operation on the segment. 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 kilobytes to 256 kilobytes 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 segment. But, in addition, it specifies that a double buffering policy should be used to stream data from the segment.

This means that after the first two transfers from the segment, each transfer from the segment replaces the data cached by the second-to-last transfer from that segment. This way, the last two chunks of data retrieved from the segment will generally be in the client cache at the same time. And, after the first two transfers, transfers from the segment generally will not result in eviction of data from other segments. This policy also greatly reduces the internal overhead of finding pages to evict.

When you perform allocation that extends a segment whose fetch policy is os_fetch_stream, the double buffering described above begins when allocation reaches an offset in the segment 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 segment or a database) 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 segment or database.

os_segment::set_lock_whole_segment()

void set_lock_whole_segment(objectstore_lock_option);

The member function os_segment::set_fetch_policy() controls whether or not a given segment is transferred to the client cache all at once. By default, even when a segment's pages are transferred all at once, only the page containing the referenced data is locked. You can override this default for a given segment, however, by passing objectstore::lock_segment_read or objectstore::lock_segment_write to set_lock_whole_segment().

A value of lock_segment_read causes pages in the segment to be read-locked when cached in response to attempted access by the client. Subsequently, upgrading to read/write locks occurs on a page-by-page basis, as needed.

A value of lock_segment_write causes the segment's pages to be write-locked when cached in response to attempted read or write access by the client. In this case, the Server assumes from the start that write access to the entire segment is desired.

Note also that this function pertains only to the current process. The initial value of this data member for existing segments is lock_as_used. The initial value for segments created by the current process is the value of os_database::set_default_lock_whole_segment() for the database in which the segment resides.

os_segment::set_null_illegal_pointers()

void set_null_illegal_pointers(os_boolean);

os_segment::set_readlock_timeout()

void set_readlock_timeout(os_int32);

os_segment::set_size()

os_unsigned_int32 set_size(os_unsigned_int32);

os_segment::set_writelock_timeout()

void set_writelock_timeout(os_int32);

os_segment::size()

os_unsigned_int32 size();

os_segment::unlock_from_cache()

void unlock_from_cache();

os_segment::unused_space()

os_unsigned_int32 unused_space() const;

Updated: 03/31/98 17:25:09