The API allows markers to be nested; that is, several markers can be in effect at the same time. Calling os_address_space_marker::release() on an outer marker releases any markers nested within it.
The os_address_space_marker::retain() function allows selective release of address space, similar to creating os_retain_address objects, but without the requirement for stack allocation (which binds the usage to a lexical scope). Call os_address_space_marker::retain() on any pointers that should remain valid across the release boundary, prior to calling release. os_address_space_marker::retain() can also be passed a marker - in this case, the address space required by the pointer is not released until that marker is released. It is not possible to use the retain function on an address to make it be released sooner, by a more nested marker - attempts to do so are ignored.
The os_address_space_marker::release() function releases address space added since the creation of the mark, minus any address space retained by calls to the os_address_space_marker::retain() function (and any retained by os_retain_address objects and os_pvars). release() can be called on a marker repeatedly, each time releasing the address space accumulated since the previous release (or since the marker was created).
If a marker is deleted and no call to os_address_space_marker::release() is made, the marker is removed and the address spaced that it controlled is now controlled by its previous marker. If there is no previous marker, the address space is not governed by any marker and is no longer incrementally releasable.
After the outermost marker is created, no more than 232-2 minus 1 additional markers can be created before the outermost one is deleted. This is true even if some or all of the inner markers are deleted.
Like objectstore::release_persistent_addresses(), markers cannot be released within nested transactions.
The implementation of os_address_space_marker::release(), besides possibly not freeing as much address space as objectstore::release_persistent_addresses(), also does not cool the client cache as much. os_address_space_marker::release() must relocate out all pages that were relocated in or modified after the marker was constructed
static os_address_space_marker *get_current();Returns the current address space marker. The current marker is defined as the most recently constructed marker that has not yet been deleted. This function can be used with nested markers.
os_unsigned_int32 get_level() const;The level of a marker is 1 if there was no current marker when it was created. Otherwise, the level is 1 greater than the level of the previously created marker. Use get_level() to quickly compare address space markers. Markers with lower levels come before those with higher levels. This function can be used with nested markers.
os_address_space_marker *get_next() const;Returns the next address space marker (or NULL if this marker is the last). The next address space marker is the first one that was created after this address space marker.
This function can be used with nested markers.
os_address_space_marker *get_previous() const;Returns the previous address space marker (or NULL if this marker is the first). The previous address space marker is the last one that was created before this address space marker. This function can be used with nested markers.
static os_address_space_marker *of(void *p);Returns the address space marker (or NULL) with the highest level that, when released, will release the address space needed for pointer p.
os_address_space_marker();Creates an os_address_space_marker.
void release();Releases the address space that was added to the PSR since the address space marker was created, or since the last time os_address_space_marker::release was called.
Deleting a marker does not does not release the address space it has marked. Conversely, releasing a marker does not deactivate, or delete, it. This means you can call the release function again on the same marker after more address space has been accumulated. os_address_space_marker::release does not affect the value of os_address_space_marker::get_current(). This function can be used with nested markers.
static void retain(
void *p,
os_address_space_marker *marker = NULL
);
Returns the address space marker (or NULL) with the highest level that, when released, releases the address space needed for pointer p. Retains space needed by pointer p back to some marker, or (if the marker is null) back past all markers.
~os_address_space_marker();Destructor function.
.
Updated: 03/31/98 17:25:09