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_protected_locals, in contrast, are always valid across transaction boundaries, as well as across databases.
Once the object referred to by an os_reference_protected_local is deleted, use of the os_reference_protected_local will cause an err_reference_not_found exception to be signaled. If the referent database has been deleted, err_database_not_found is signaled.
You can create a reference to serve as substitute for a pointer by initializing a variable of type os_reference_protected_local with the pointer, or by assigning the pointer to a variable of type os_reference_protected_local (implicitly invoking the conversion constructor os_reference_protected_local::os_reference_protected_local(void*)). This pointer must not point to transient memory. In general, a pointer can be used anywhere an os_reference_protected_local is expected, and the conversion constructor will be invoked.
part *a_part = ... ;
os_reference_protected_local part_ref = a_part;
When the member function resolve() is applied to an os_reference_protected_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>.
os_boolean deleted(os_database *db) const;Returns 1 (true) if the object to which the specified reference refers has been deleted from the specified database; 0 (false) otherwise.
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_protected_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.
void forget(os_database *db);Frees the memory in the underlying table used to associate the specified os_reference_protected_local with its referent in the specified database. Subsequent use of the os_reference_protected_local will result in a run-time error.
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_protected_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_protected_local to a given referent.
void load(const char*);If the specified char* points to a string generated from a reference with os_reference_protected_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_protected_local &operator=(
const os_reference_protected_local&
);
Establishes the referent of the right operand as the referent of the left operand.
os_reference_protected_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_protected_local const&) const;Returns 1 if the arguments have the same referent; returns 0 otherwise.
os_boolean operator !() const;Returns nonzero if the reference has no current referent.
os_boolean operator !=(
os_reference_protected_local const&
) const;
Returns 1 if the arguments have different referents; returns 0 otherwise.
os_boolean operator <(os_reference_protected_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_protected_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_protected_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_protected_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_protected_local(const void *);Constructs a reference to substitute for the specified void*. If the void* points to transient memory, err_reference_to_transient is signaled. 0 is a legal argument.
void* resolve(const os_database*);Returns the void* for which the specified os_reference_protected_local is a substitute. The database containing the storage pointed to by the void* must be specified. If the referent has been deleted, err_reference_not_found is signaled.
Updated: 03/31/98 17:25:09