ObjectStore C++ API Reference

os_object_cluster

An object cluster is a portion of a segment (see the class os_segment) into which related objects can be clustered at allocation time. An object cluster can contain as little as a single small object or as much as 64 Kbytes of memory.

You can improve application performance by clustering together objects that are expected to be used together by applications. This reduces the number of disk and network transfers the applications will require. Moreover, allocating objects in different clusters can increase concurrency, since one process's lock on an object in one cluster never blocks access by other processes to objects in other clusters (assuming os_segment::lock_whole_segment has value objectstore::lock_as_used - the default - for the segments containing the clusters).

A cluster of a specified size is created with the create_object_cluster() member of the class os_segment. A new object can be allocated in a cluster using one of the special overloadings of ::operator new() (see the description of ::operator new()), or, in some cases, a class-specific new or create() operation tailored for object clustering.

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.hh>.

os_object_cluster::destroy()

void destroy(
      forced_destroy_enum option = 
            os_object_cluster::destroy_if_empty
);

Destroys the specified os_object_cluster if either the cluster contains no nondeleted objects or the os_int32 argument is the enumerator os_object_cluster::destroy_always. If invoked on a nonempty cluster with os_object_cluster::destroy_if_empty as argument, the exception err_destroy_cluster_not_empty is signaled.

os_object_cluster::destroy_always

Enumerator, used as an argument to os_object_cluster::destroy(), indicating that destruction of the cluster should proceed even if the specified cluster contains nondeleted objects. Destroying a cluster results in deletion of all the objects it contains, but does not result in execution of the destructors for the deleted objects.

os_object_cluster::destroy_if_empty

Enumerator, used as an argument to os_object_cluster::destroy(), indicating that destruction of the cluster should proceed only if the specified cluster contains no nondeleted objects. Destroying a cluster results in deletion of all the objects it contains, but does not result in execution of the destructors for the deleted objects.

os_object_cluster::get_info()

void get_info(
      os_int32 &cluster_size, 
      os_int32 &free, 
      os_int32 &contig_free
) const;

Modifies cluster_size to refer to the size in bytes of the specified os_object_cluster; modifies free to refer to the number of unallocated bytes in the cluster; modifies contig_free to refer to the number of bytes in the largest contiguous portion of unallocated memory in the cluster.

os_object_cluster::is_empty()

os_boolean is_empty() const;

Returns nonzero (true) if the specified os_object_cluster contains no nondeleted objects; returns 0 (false) otherwise.

os_object_cluster::of()

static os_object_cluster *of(const void *obj);

Returns a pointer to the os_object_cluster containing the object pointed to by obj. If the object is not contained in a cluster, 0 is returned.

os_object_cluster::segment_of()

os_segment *segment_of() const;

Returns a pointer to the segment containing the specified os_object_cluster.

[previous] [next]

Copyright © 1997 Object Design, Inc. All rights reserved.

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