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.
part *a_part = ... ;
os_reference_local 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);
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 &operator=(const os_reference_local&);Establishes the referent of the right operand as the referent of the left operand.
os_reference_local &operator=(const void*);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 and second arguments 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 and second arguments 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 and second arguments 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 and second arguments 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(const void*);Constructs a reference to substitute for the specified void*.
void *resolve(const os_database*) const;Returns the valid void* for which the specified reference is a substitute. The database containing the storage pointed to by the void* must be specified.
Updated: 03/31/98 17:25:09