NAME

ObjStore::Reference - a listing of APIs

SYNOPSIS

Fortunately, you will probably not need to use most of the API. In general, the API mostly mirrors the ObjectStore C++ API. Refer to the ObjectStore documentation for exact symantics.

DESCRIPTION

Primarily, the API is exhibited here to make it seem like this extension has a difficult and steep learning curve (it doesn't).

The API for ::UNIVERSAL is probably of greatest interest to ex-C++ developers.

`ObjStore`

$db = ObjStore::open($pathname, $read_only, $mode);
Also see ObjStore::HV::Database.
$name = ObjStore::release_name()
$version = ObjStore::os_version()
$yes = ObjStore::network_servers_available();
$num = ObjStore::return_all_pages();
$size = ObjStore::get_page_size();
@Servers = ObjStore::get_all_servers();
$in_abort = ObjStore::abort_in_progress();
$num = ObjStore::get_n_databases();

`::Server`

$name = $s->get_host_name();
$is_broken = $s->connection_is_broken();
$s->disconnect();
$s->reconnect();
@Databases = $s->get_databases();

`::Database`

Also see ObjStore::HV::Database.

$open_mode = $db->is_open();
$s = $db->create_segment($comment);
$value = $db->root($root_name => sub{ $new_value });
This is the recommended API for roots. If the given root is not found, creates a new one. Returns the root's current value.

In general, you should try to avoid using roots. Roots have an unnatural API for perl: hashes can nest but roots cannot. Roots are similar to a necessary but annoying accounting detail. It is much better practice to use ObjStore::HV::Database or ObjStore::ServerDB.
$s = $db->get_segment($segment_number);
Be aware that this method (correctly) never returns an error. The only way to know which segments are actually created in a database is to iterate through get_all_segments.
@Segments = $db->get_all_segments();
$db->close();
$db->destroy();
$db->get_default_segment_size();
$db->get_sector_size();
$db->size();
$db->size_in_sectors();
$ctime = $db->time_created();
$can_write = $db->is_writable();
$db->set_fetch_policy(policy[, blocksize]);
Policy can be one of segment, page, or stream.
$db->set_lock_whole_segment(policy);
Policy can be one of as_used, read, or write.
@Roots = $db->get_all_roots();
$root = $db->create_root($root_name);
$root = $db->find_root($root_name);
$db->destroy_root($root_name);
Destroys the root with the given name if it exists.

`::Root`

$root->get_name();
$root->get_value();
$root->set_value($new_value);
$root->destroy();

`::Transaction`

ObjectStore transactions and exceptions are seemlessly integrated into perl. ObjectStore exceptions cause a die in perl just as perl exceptions can cause a transaction abort.

    begin 'update', sub {
        $top = $db->root('top');
        $top->{abc} = 3;
        die "Oops!  abc should not change!";       # aborts the transaction
    };
    die if $@;

There are three types of transactions: read, update, and abort_only. The default is read. Read transaction are blindingly fast.

    begin 'read', sub {
        my $var = $db->root('top');
        $var->{abc} = 7;        # write to $var triggers exception
    };
    die if $@;

(In a read transaction, you are not allowed to modify persistent data.)

$T = ObjStore::Transaction::get_current();
$type = $T->get_type();
$pop = $T->get_parent();
$T->prepare_to_commit();
$yes = $T->is_prepare_to_commit_invoked();
$yes = $T->is_prepare_to_commit_completed();
$ObjStore::TRANSACTION_PRIORITY
ObjStore::set_max_retries($oops);
my $oops = ObjStore::get_max_retries();
my $yes = ObjStore::is_lock_contention();
my $type = ObjStore::get_lock_status($ref);
my $tm = ObjStore::lock_timeout($rw);
$rw should be either 'read' or 'write'. Return value of 1 == 1 second. Undef indicates that there is no timeout.
ObjStore::lock_timeout($rw, $tm);
Set lock timeouts.

Dynamic transactions are also available. See ObjStore::Serve.

`::Segment`

$s->set_comment($comment);
$s->destroy();
$size = $s->size();
$yes = $s->is_empty();
$yes = $s->is_deleted();
$num = $s->get_number();
$comment = $s->get_comment();
$s->lock_into_cache();
$s->unlock_from_cache();
$s->set_fetch_policy($policy[, $size]);
Policy can be one of segment, page, or stream.
$s->set_lock_whole_segment($policy);
Policy can be one of as_used, read, or write.

`::Notification`

Easy event dispatching for network distributed objects. See ObjStore::notify.

ObjStore::subscribe(...);
ObjStore::unsubscribe(...);
set_queue_size($size);
($size, $pending, $overflow) = queue_status();
$fd = _get_fd();
$n = receive([$timeout]);
Receive();
$db = $n->get_database;
$p = $n->focus;
$why = $n->why;

`::UNIVERSAL`

All persistent objects inherit from ObjStore::UNIVERSAL.

overload
Stringify, boolean & numeric coersion, equality tests.
os_class
Reports the natural persistent class of the object. All persistent objects must have this class in their @ISA tree.
rep_class
Reports the representation's class.
bless
In addition to the usual meaning of bless, ObjStore bless stores the current @ISA tree and the VERSION of every member of the @ISA tree.
$o-isa($baseclass)>
Whether the $baseclass was part of the @ISA tree at the moment of blessing.
$o-versionof($baseclass)>
Returns the version of the $baseclass (at the moment of blessing).
$o-subscribe()> and $o-unsubscribe()>
These might not be available per-object. Only per-segment or per-database. XXX
$o-notify($why, $when)>
Sends a notification to subscribers. When can be either 'now' or 'commit'. The $when parameter might be required. [Also under consideration is a means to bunch notifications together for batch send. XXX]
Of
database_of and segment_of are available as methods.
posh
posh behavior can be customized by adding special methods that are detected by posh. See the posh section.

To make everything seem apparently consistent, ObjStore::Database (while not really being a storable object) is lavishly special-cased to support most (maybe all!) of the above features.

CPAN RT