ObjectStore C++ API Reference

os_Reference

Instances of the class os_Reference can be used as substitutes for cross-database and cross-transaction pointers. References are valid under a wider array of circumstances than are pointers to persistent storage.

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_References, in contrast, are always valid across transaction boundaries, as well as across databases.

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.

The class os_Reference is parameterized, with a parameter for indicating the type of the object referred to by a reference. This means that when specifying os_Reference 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 the name of the referent type enclosed in angle brackets (< >):

      os_Reference<referent-type-name>
The referent type must be a class. For references to built-in types such as int and char see os_reference.

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.

You can create a reference to serve as substitute for a pointer of type T* by initializing a variable of type os_Reference<T> with a T*, or by assigning a T* to a variable of type os_Reference<T> (implicitly invoking the conversion constructor os_Reference::os_Reference(T*)).

      part *a_part; ...
      os_Reference<part> part_ref = a_part;
Usually, when an os_Reference<T*> is used where a T* is expected, os_Reference::operator ->() or os_Reference::operator T*() is implicitly invoked, returning a valid pointer to the object referred to by the os_Reference.

      printf("%d\n", part_ref->part_id);
Not all C++ operators have special reference class overloadings. References do not behave like pointers in the context of [] and ++, for example.

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.

Each instance of this class stores a relative pathname to identify the referent database. The pathname is relative to the lowest common directory in the pathnames of the referent database and the database containing the reference. For example, if a reference stored in /A/B/C/db1 refers to data in /A/B/D/db2, the lowest common directory is A/B, so the relative pathname ../../D/db2 is used.

This means that if you copy a database containing a reference, the reference in the copy and the reference in the original might refer to different databases. To change the database a reference refers to, you can use the ObjectStore utility oschangedbref. See ObjectStore Management.

Using memcpy() with persistent os_References
You can use the C++ memcpy() function to copy a persistent os_Reference only if the target object is in the same segment as the source object. This is because all persistent os_References use os_segment::of(this) for os_Reference resolution processing and the resoultion will be incorrect if the os_Reference has been copied to a different segment.

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_Reference::dump()

char *dump(const char *db_str) const;
Returns a heap-allocated text string representing the specified reference. However, unlike the string returned by the char * os_Reference::dump(void) method, this string does not contain an absolute database path. The returned string is intended to be used as the dump_str parameter of an os_Reference load method of the form load(const char* dump_str, os_database* db). It is the responsibility of the caller of load to ensure that the db parameter passed to the load method is the same as the database of the dumped reference. It is the user's responsibility to delete the returned string when finished using the string.

This operation is useful in those applications in which you do not want the overhead of storing the absolute database path in the dumped strings.

os_Reference::get_database()

os_database *get_database() const;
Returns a pointer to the database containing the object referred to by the specified reference.

os_Reference::get_database_key()

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.

os_Reference::get_open_database()

os_database *get_open_database() const;
Returns a pointer to the database containing the object referred to by the specified os_Reference. Opens the database.

os_Reference::get_os_typespec()

static os_typespec *get_os_typespec();
Returns an os_typespec* for the class os_Reference.

os_Reference::hash()

os_unsigned_int32 hash() const;
Returns an integer suitable for use as a hash table key. The value returned is always the same for a reference to a given referent.

os_Reference::load()

void load(const char* dump_str, const os_database* db);
The dump_str parameter is assumed to be the result of a call to a compatible os_Reference dump method. It is the responsibility of the caller of load to ensure that the db parameter passed to the load method is the same as the database of the originally dumped reference.

The loaded reference refers to the same object as the os_Reference used to dump the string as long as the db parameter is the same as the database of the dumped reference.

The exception err_reference_syntax is raised if the dump_str is not in the expected format or if the dump_str was dumped from a protected reference.

os_Reference::operator T*()

operator T*() const;
Returns the valid T* for which the specified reference is a substitute.

os_Reference::operator ->()

T* operator ->() const;
Returns the valid T* for which the specified reference is a substitute.

os_Reference::operator =()

os_Reference<T> &operator=(const os_Reference<T>&);
Establishes the referent of the right operand as the referent of the left operand.

os_Reference<T> &operator=(const T*);
Establishes the object pointed to by the right operand as the referent of the left operand.

os_Reference::operator ==()

os_boolean operator ==(os_Reference const&) const;
Returns 1 if the arguments have the same referent; returns 0 otherwise.

os_Reference::operator !()

os_boolean operator !(os_Reference const&) const;
Returns 1 if the os_Reference argument is pointing to NULL; returns 0 otherwise.

os_Reference::operator !=()

os_boolean operator !=(os_Reference const&) const;
Returns 1 if the arguments have different referents; returns 0 otherwise.

os_Reference::operator <()

os_boolean operator <(os_Reference 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_Reference:operator >()

os_boolean operator >(os_Reference 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_Reference:operator >=()

os_boolean operator >=(os_Reference 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_Reference:operator <=()

os_boolean operator <=(os_Reference 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::os_Reference()

os_Reference(T*);
Constructs a reference to substitute for the specified T*.

os_Reference::resolve()

T *resolve() const;
Returns the valid T* for which the specified reference is a substitute.



[previous] [next]

Copyright © 1997 Object Design, Inc. All rights reserved.

Updated: 03/31/98 17:25:09