The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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.