The clustering information indicates the database in which the new object is to be stored, and can also specify the particular segment or object cluster within that database in which the object is to reside. Specifying the transient database or segment results in transient allocation.
The argument indicating the type of the new object is an instance of the class os_typespec.
Each function returns a pointer to newly allocated memory. Persistent memory is initialized to null by ObjectStore.
ObjectStore supports cross-database pointers. You can allow cross-database pointers from a given database or segment with os_database::allow_external_pointers() or os_segment::allow_external_pointers().
If cross-database pointers are not enabled for a database or segment, and memory allocated within it is assigned pointers to memory allocated in a different database, the pointers are valid only until the end of the outermost transaction in which the assignment occurred.
ObjectStore also supports cross-transaction pointers. You can enable cross-transaction pointers at any point in the execution of an application with objectstore::retain_persistent_addresses().
If cross-transaction pointers are not enabled, a pointer from transiently allocated memory to persistently allocated memory is valid only until the end of the outermost transaction in which the pointer was assigned to that transient memory. Attempts to dereference an invalid pointer in subsequent transactions might access arbitrary data, unless data from the segment was committed only with the segment in check_illegal_pointers mode. See os_segment::check_illegal_pointers().
If persistent memory is assigned pointers to transiently allocated memory, the pointers are valid only until the end of the outermost transaction in which the assignment occurred.
Do not pass pointers to persistent memory to non-ObjectStore processes using system calls or interprocess communication.
Before a persistent object can be created with operator new(), the database in which it is to be stored must exist. Moreover, this database must be opened by the process performing the creation, and this process must have a transaction in progress.
The type os_int32, mentioned below, is defined as a signed 32-bit integer type.
void *::operator new(size_t, os_database*, os_typespec*)If this form is used, a newly created object of the type specified by the os_typespec is stored in the specified database. If the transient database (see os_database::get_transient_database()) is specified, the new object is transiently allocated. If you specify the transient database, you can supply 0 for the os_typespec* argument.
void *::operator new(size_t, os_database*, os_typespec*, os_int32)If this form is used, a newly created array of objects of the type specified by the os_typespec is stored in the specified database. If the transient database (see os_segment::get_transient_database()) is specified, the new array is transiently allocated. If you specify the transient database, you can supply 0 for the os_typespec* argument. The os_int32 specifies the number of elements in the new array. On OS/2, an overloading of ::operator new[]() is provided instead. It has the same arguments and return type.
void *::operator new(size_t, os_segment*, os_typespec*)If this form is used, a newly created object of the type specified by the os_typespec is stored in the specified segment (unless that segment is the schema segment, in which case err_misc is signaled). If the transient segment (see os_database::get_transient_segment()) is specified, the new object is transiently allocated. If you specify the transient segment, you can supply 0 for the os_typespec* argument.
void *::operator new(size_t, os_segment*, os_typespec*, os_int32)If this form is used, a newly created array of objects of the type specified by the os_typespec is stored in the specified segment (unless that segment is the schema segment, in which case err_misc is signaled). If the transient segment (see os_segment::get_transient_segment()) is specified, the new array is transiently allocated. If you specify the transient segment, you can supply 0 for the os_typespec* argument. The os_int32 specifies the number of elements in the new array. On OS/2, an overloading of ::operator new[]() is provided instead. It has the same arguments and return type.
void *::operator new(size_t, os_object_cluster*, os_typespec*)If this form is used, a newly created object of the type specified by the os_typespec is stored in the specified object cluster, unless the new object does not fit in the cluster, in which case err_cluster_full is signaled.
void *::operator new(size_t, os_object_cluster*, os_typespec*, os_ int32)If this form is used, a newly created array of objects of the type specified by the os_typespec is stored in the specified object cluster, unless the new array does not fit in the cluster, in which case err_cluster_full is signaled. The os_int32 specifies the number of elements in the new array. On OS/2, an overloading of ::operator new[]() is provided instead. It has the same arguments and return type.
Note: The overloadings of operator new() described in this section can be used for transient as well as persistent allocation. To allocate transient memory, supply a pointer to the transient database or segment for the os_database* or os_segment* argument. If you specify the transient database or segment, you can supply 0 for the os_typespec* argument.
Performing os_database::of() or os_segment::of() on a pointer to transient memory returns a pointer to the transient database or segment, respectively. The following static member functions also return a pointer to the transient database or segment: os_database::get_transient_database() and os_segment::get_transient_segment().
Updated: 03/31/98 17:30:04