C++ API Reference

Chapter 3 System-Supplied Global Functions

Some system-supplied interface functions are not members of any class but are global C++ functions. These functions are

Functions

The system-supplied global functions are listed alphabetically in this chapter.

::operator delete()

Persistent storage can be reclaimed using ::operator delete operator, just as it would be used for transient objects. ObjectStore determines whether the storage is persistent or transient.

When a persistent object is deleted using ::operator delete(), the database in which it is to be stored must be opened by the process performing the deletion, and this process must have a transaction in progress.

Applications can register their own transient delete; see objectstore::set_transient_delete_function(). If you want to override ObjectStore's global ::operator delete(), you must define it to delete both transient and persistent memory. To delete persistent memory, the definition of ::operator delete() must include a call to objectstore::free_memory(); see objectstore::free_memory().

Required header file

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

void ::operator delete()

Deletes the specified object from storage. The argument must point to the beginning of an object's storage. If it points to the middle of an object, the exception err_invalid_deletion is signaled. This might happen, for example, if the argument points to the fifth element of a persistent array, or if the argument has been cast from a D* to a B*, where class D is derived directly from class B and another class.

::operator new()

ObjectStore provides overloadings of ::operator new() for allocating persistent or transient storage, using the following syntax:

Syntax

void* ::operator new(size_t, clustering_info, typespec, elements)

The arguments have the following meanings:

size_t is the size of the new object. This argument is optional and, if not specified, is supplied by the system.
clustering_info specifies clustering information, that is, the database, segment, or cluster in which to allocate storage for the new object. Specifying a transient database, segment, or cluster results in transient allocation.
typespec specifies the type of the new object. This argument is an instance of the class os_typed_pointer_void.
If new is used to create an array, elements specifies the number of elements.

Each overloading returns a pointer to newly allocated memory. Persistent memory is initialized to null by ObjectStore.

void *::operator new(size_t, os_database*,
      os_typespec*[, os_int32])

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. If you are allocating for an array objects, use the argument os_int32 (a signed 32-bit integer type) to specify the number of elements.

void *::operator new(size_t, os_segment*, os_typespec*[, os_int32])

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_segment::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. If you are allocating for an array of objects, use the argument os_int32 (a signed 32-bit integer type) to specify the number of elements.

void *::operator new(size_t, os_cluster*, os_typespec*[, os_int32])

If this form is used, a newly created object of the type specified by the os_typespec is stored in the specified cluster unless the new object does not fit in the cluster, in which case err_cluster_full is signaled. If this argument is the address of transient memory, the new object is transiently allocated. If you are allocating transient storage, you can supply 0 for the os_typespec* argument. If you are allocating for an array objects, use the argument os_int32 (a signed 32-bit integer type) to specify the number of elements.

void *::operator new(size_t, os_cluster::with(), 
      os_typespec* [, os_int32])

If this form is used, a newly created object of the type specified by the os_typespec is stored as close as possible to the object specified as the argument to os_cluster::with(); see os_cluster::with(). If the transient segment (see os_cluster::get_transient_cluster()) is specified, the new object is transiently allocated. If you specify the transient cluster, you can supply 0 for the os_typespec* argument. If you are allocating for an array objects, use the argument os_int32 (a signed 32-bit integer type) to specify the number of elements.

os_cluster::with() returns an automatic variable of the class os_cluster_with. This object contains a pointer to the object near which you want to allocate. Following is an example of the way to use this method in operator new(), which allocates storage for obj2 as close as possible to obj1:

a_class *obj2 = new(os_cluster::with(obj1), a_typespec) a_class;

Note

For optimum clustering, use the os_cluster::with() overloading of ::operator new(). This overloading has the added advantage that os_cluster::with() returns an automatic variable that does not require the user to delete it explicitly. For more information, see C++ API User Guide.

template < class T > 
void* operator new (
      size_t,
      const os_Allocator<T>&, 
      void *hint = 0
);

For use with the ObjectStore allocator framework. Calls os_Allocator<T>::allocate(1, hint).

template < class T > 
void* operator new (
      size_t,
      const os_Allocator<T>&, 
      size_t number_of_elements,
      void *hint = 0
);

For use with the ObjectStore allocator framework. Calls os_Allocator<T>::allocate(number_of_elements, hint).

::operator ==()

The following functions are for use with the ObjectStore allocator framework.

template < class T > 
os_boolean operator==(
      const os_Allocator<T>&, 
      const os_Allocator<T>&
);

Returns nonzero if the extended allocators associated with the specified allocators can safely be used to allocate objects of the same type; returns 0 otherwise. If the corresponding comparison operator for extended allocators is not implemented by the allocator implementer, this function always returns 0.

os_boolean operator==(
      const os_extended_allocator&, 
      const os_extended_allocator&
)

Returns nonzero if the specified extended allocators can safely be used to allocate objects of the same type; returns 0 otherwise. If not defined by the derived type, this function always returns 0.

os_boolean operator==( 
      const os_string& str_left, 
      const os_string& str_right 
) ;

Returns nonzero if the strings encapsulate character arrays for which strcmp() returns 0; returns 0 otherwise.

os_boolean operator==( 
      const char* ch_str_left, 
      const os_string& str_right 
) ;

Returns nonzero if strcmp() returns 0 for str_left and the character-array value of str_right; returns 0 otherwise.

os_boolean operator==( 
      const os_string& str_left, 
      const char* ch_str_right 
) ;

Returns nonzero if strcmp() returns 0 for str_left and the character-array value of str_left; returns 0 otherwise.

::operator !=()

The following functions are for use with the ObjectStore allocator framework.

template < class T > 
os_boolean operator!=(
      const os_Allocator<T>&, 
      const os_Allocator<T>&
);

Returns nonzero if the extended allocators associated with the specified allocators cannot safely be used to allocate objects of the same type; returns 0 otherwise. If the corresponding comparison operator for extended allocators is not implemented by the allocator implementer, this function always returns 1.

os_boolean operator!=(
      const os_extended_allocator&, 
      const os_extended_allocator&
)

Returns nonzero if the specified extended allocators cannot safely be used to allocate objects of the same type; returns 0 otherwise. If not defined for the derived type, this function always returns 0.

os_boolean operator!=( 
      const os_string& str_left, 
      const os_string& str_right 
) ;

Returns nonzero if the strings encapsulate character arrays for which strcmp() returns nonzero; returns 0 otherwise.

os_boolean operator!=( 
      const char* ch_str_left, 
      const os_string& str_right 
) ;

Returns nonzero if strcmp() returns nonzero for str_left and the character-array value of str_right; returns 0 otherwise.

os_boolean operator!=( 
      const os_string& str_left, 
      const char* ch_str_right
) ;

Returns nonzero if strcmp() returns 0 for str_left and the character-array value of str_left; returns 0 otherwise.

::os_fetch()

Retrieves the value of a specified data member for a specified object.

void *os_fetch

void *os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      void *&val
);

Retrieves the value of the member represented by mem for the object obj by setting val to a reference to the value. err_mop is signaled if the value type of the specified member is not compatible with val.

unsigned long os_fetch

unsigned long os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      unsigned long &val
);

long os_fetch

long os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      long &val
);

unsigned int os_fetch

unsigned int os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      unsigned int &val
);

int os_fetch

int os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      int &val
);

unsigned short os_fetch

unsigned short os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      unsigned short &val
);

short os_fetch

short os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      short &val
);

unsigned char os_fetch

unsigned char os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      unsigned char &val
);

char os_fetch

char os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      char &val
);

float os_fetch

float os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      float &val
);

double os_fetch

double os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      double &val
);

long double os_fetch

long double os_fetch(
      const void* obj, 
      const os_member_variable& mem, 
      long double &val
);

::os_fetch_address()

Retrieves the address of a specified data member for a given object or the address of the subobject corresponding to a specified base class for a given object.

void *os_fetch_address

void *os_fetch_address(
      void *obj, 
      const os_member_variable& mem
);

Retrieves the address of the data member mem for the object pointed to by obj. err_mop is signaled if mem is an os_field_member_variable.

void *os_fetch_address

void *os_fetch_address(
      void *obj, 
      const os_base_class &b
);

Retrieves the address of the subobject corresponding to base class b for the object pointed to by obj.

::os_store()

Stores the value of a specified data member for a specified object. There are several overloadings:

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const void *val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const unsigned long val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const long val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const unsigned int val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const int val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const unsigned short val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const short val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const unsigned char val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const char val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const float val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const double val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

void os_store

void os_store(
      void* obj, 
      const os_member_variable& mem, 
      const long double val
);

Establishes val as the value of the member represented by mem for the object obj. err_mop is signaled if the value type of the specified member is not compatible with val.

[previous] [next]

Updated: 03/15/99 16:44:18