A pointer to persistent storage assigned to transient memory is valid only until the end of the outermost transaction in which the assignment occurred, unless objectstore::retain_persistent_addresses() is used. In addition, a pointer to storage in one database assigned to storage in another database is valid only until the end of the outermost transaction in which the assignment occurred, unless os_database::allow_external_pointers() or os_segment::allow_external_pointers() is used.
os_Reference_locals, in contrast, are always valid across transaction boundaries, as well as across databases.
An os_Reference_local is smaller than an os_Reference, but resolving it requires explicit specification of the referent database.
Once the object referred to by a reference is deleted, use of the reference accesses arbitrary data and might cause a segmentation violation. But see os_Reference_protected_local.
os_Reference_local<referent-type-name>The referent type must be a class. For local references to built-in types, such as int and char, see os_reference_local.
The referent type parameter, T, occurs in the signatures of some of the functions described below. The parameter is used by the compiler to detect type errors.
part *a_part = ... ;
os_Reference_local<part> part_ref = a_part;
When the member function resolve() is applied to an os_Reference_local, with a pointer to the referent database as argument, a valid pointer to the referent object is returned.
printf("%d\n", part_ref.resolve(db1)->part_id);
In some cases involving multiple inheritance, comparing two references has a different result from comparing the corresponding pointers. For example, for == comparisons, if the referent type of one operand is a nonleftmost base class of the referent type of the other operand, the result is always 1. 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>.
char *dump(const char *database_name) const;Returns a heap-allocated text string representing the specified reference. When this string is passed to os_Reference_local::load(), the result is a reference to the same object referred to by the dumped reference. It is the user's responsibility to delete the returned string.
char* get_database_key(const char* dump_str);Returns a heap-allocated string containing the database_key component of the string dump_str. dump_str must have been generated using the dump operation. Otherwise, the exception err_reference_syntax is raised. It is the user's responsibility to delete the returned string when finished using the string.
static os_typespec *get_os_typespec();Returns an os_typespec* for the class os_Reference_local.
os_unsigned_int32 hash() const;Returns an integer suitable for use as a hash table key. The value returned is always the same for an os_Reference_local to a given referent.
void load(const char*);If the specified char* points to a string generated from a reference with os_Reference_local::dump(), calling this function makes the specified reference refer to the same object referred to by the reference used to generate the string.
os_Reference_local<T> &operator=(const os_Reference_local<T>&);Establishes the referent of the right operand as the referent of the left operand.
os_Reference_local<T> &operator=(const T*);Establishes the object pointed to by the right operand as the referent of the left operand.
os_boolean operator ==(os_Reference_local const&) const;Returns 1 if the arguments have the same referent; returns 0 otherwise.
os_boolean operator !=(os_Reference_local const&) const;Returns 1 if the arguments have different referents; returns 0 otherwise.
os_boolean operator <(os_Reference_local const&) const;If the first argument and second argument refer to elements of the same array or one beyond the end of the array, a return value of 1 indicates that the referent of the first argument precedes the referent of the second, and a return value of 0 indicates that it does not. Otherwise the results are undefined.
os_boolean operator >(os_Reference_local const&) const;If the first argument and second argument refer to elements of the same array or one beyond the end of the array, a return value of 1 indicates that the referent of the first argument follows the referent of the second, and a return value of 0 indicates that it does not. Otherwise the results are undefined.
os_boolean operator >=(os_Reference_local const&) const;If the first argument and second argument refer to elements of the same array or one beyond the end of the array, a return value of 1 indicates that the referent of the first argument follows or is the same as the referent of the second, and a return value of 0 indicates that it does not. Otherwise the results are undefined.
os_boolean operator <=(os_Reference_local const&) const;If the first argument and second argument refer to elements of the same array or one beyond the end of the array, a return value of 1 indicates that the referent of the first argument precedes or is the same as the referent of the second, and a return value of 0 indicates that it does not. Otherwise the results are undefined.
os_Reference_local(T*);Constructs a reference to substitute for the specified T*.
T* resolve(const os_database*) const;Returns the valid T* for which the specified reference is a substitute. The database containing the storage pointed to by the T* must be specified.
Updated: 03/31/98 17:25:09