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 err_reference_not_found to be signaled. If the referent database has been deleted, err_database_not_found is signaled.
The class os_Reference_protected_local is parameterized, with a parameter for indicating the type of the object referred to by a reference. This means that when specifying os_Reference_protected_local as a function's formal parameter, or as the type of a variable or data member, you must specify the parameter - the reference's referent type. You do this by appending to os_Reference_protected_local the name of the referent type enclosed in angle brackets (< >):
os_Reference_protected_local<referent-type-name>The referent type must be a class. For protected local references to built-in types, such as int and char, see os_reference_protected_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_protected_local<part> 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);
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. This is because comparing references never results in the pointer adjustment described in Section 10.3c of the C++ Annotated Reference Manual.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.
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.
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.
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<T> &operator=(
const os_Reference_protected_local<T>&
);
Establishes the referent of the right operand as the referent of the left operand.
os_Reference_protected_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_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 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_protected_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_protected_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_protected_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_protected_local(T*);Constructs a reference to substitute for the specified T*. If the T* points to transient memory, err_reference_to_transient is signaled. 0 is a legal argument.
T* resolve(const os_database*) const;Returns the T* for which the specified os_Reference_protected_local is a substitute. The database containing the storage pointed to by the T* must be specified. If the referent has been deleted, err_reference_not_found is signaled. If the referent database has been deleted, err_database_not_found is signaled.
Updated: 03/31/98 17:25:09