ObjectStore C++ API Reference

os_reference_transient

Instances of the class os_reference_transient can be used as substitutes for cross-transaction pointers. The reference must be allocated transiently.

Once the object referred to by a reference is deleted, use of the reference accesses arbitrary data and might cause a segmentation violation.

You can create a reference to serve as substitute for a pointer by initializing a variable of type os_reference_transient with the pointer, or by assigning the pointer to a variable of type os_reference_transient (implicitly invoking the conversion constructor os_reference_transient::os_reference_transient(void*)). In general, a pointer can be used anywhere an os_reference_transient is expected, and the conversion constructor will be invoked.

      part *a_part = ... ;
      os_reference_transient part_ref = a_part;
When an os_reference_transient is cast to pointer-to-referent-type (that is, pointer to the type of object referred to by the reference), os_reference_transient::operator void*() is implicitly invoked, returning a valid pointer to the object referred to by the os_reference_transient.

      printf("%d\n", (part*)(part_ref)->part_id);
Performing the member function resolve() on an os_reference_transient returns a valid pointer to the object referred to by the os_reference_transient.

      printf("%d\n", part_ref.>resolve()->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_reference_transient::dump()

char *dump(const char *db_str) const;
Returns a heap-allocated string representing the specified reference. However, unlike the string returned by char* os_reference_transient::dump(void) method, the returned string does not contain an absolute database pathname. The returned string is intended to be used as the dump_str parameter of 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_transient::get_database_key()

char* get_database_key(const char* dump_str);
Returns the substring of dump_str that was the database key component of the dump string. dump_str must have been generated using the dump operation. Otherwise, the exception err_reference_syntax is raised. Note that this operation can be used with dump strings that contain the absolute pathname of the database.

os_reference_transient::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_transient::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_transient 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 will refer 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.

os_reference_transient::operator void*()

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

os_reference_transient::operator =()

os_reference_transient &operator=(
const os_reference_transient&
);
Establishes the referent of the right operand as the referent of the left operand.

os_reference_transient &operator=(const void*);
Establishes the object pointed to by the right operand as the referent of the left operand.

os_reference_transient::operator ==()

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

os_reference_transient::operator !=()

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

os_reference_transient::operator <()

os_boolean operator <(os_reference_transient 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_transient::operator >()

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

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

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

os_reference_transient(const void*);
Constructs a reference to substitute for the specified void*.

os_reference_transient::resolve()

void* resolve() const;
Returns the valid void* 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