=head1 NAME
ObjStore::Reference - a listing of APIs
=head1 SYNOPSIS
Fortunately, you will probably not need to use most of the API. In
general, the API mostly mirrors the C<ObjectStore> C<C++> API. Refer
to the C<ObjectStore> documentation for exact symantics.
=head1 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 C<::UNIVERSAL> is probably of greatest interest to
ex-C<C++> developers.
=head2 C<ObjStore>
=over 4
=item * $db = ObjStore::open($pathname, $read_only, $mode);
Also see L<ObjStore::HV::Database>.
=item * $name = ObjStore::release_name()
=item * $version = ObjStore::os_version()
=item * $yes = ObjStore::network_servers_available();
=item * $num = ObjStore::return_all_pages();
=item * $size = ObjStore::get_page_size();
=item * @Servers = ObjStore::get_all_servers();
=item * $in_abort = ObjStore::abort_in_progress();
=item * $num = ObjStore::get_n_databases();
=back
=head2 C<::Server>
=over 4
=item * $name = $s->get_host_name();
=item * $is_broken = $s->connection_is_broken();
=item * $s->disconnect();
=item * $s->reconnect();
=item * @Databases = $s->get_databases();
=back
=head2 C<::Database>
Also see L<ObjStore::HV::Database>.
=over 4
=item * $open_mode = $db->is_open();
=item * $s = $db->create_segment($comment);
=item * $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 L<ObjStore::HV::Database> or
L<ObjStore::ServerDB>.
=item * $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 C<get_all_segments>.
=item * @Segments = $db->get_all_segments();
=item * $db->close();
=item * $db->destroy();
=item * $db->get_default_segment_size();
=item * $db->get_sector_size();
=item * $db->size();
=item * $db->size_in_sectors();
=item * $ctime = $db->time_created();
=item * $can_write = $db->is_writable();
=item * $db->set_fetch_policy(policy[, blocksize]);
Policy can be one of C<segment>, C<page>, or C<stream>.
=item * $db->set_lock_whole_segment(policy);
Policy can be one of C<as_used>, C<read>, or C<write>.
=item * @Roots = $db->get_all_roots();
=item * $root = $db->create_root($root_name);
=item * $root = $db->find_root($root_name);
=item * $db->destroy_root($root_name);
Destroys the root with the given name if it exists.
=back
=head2 C<::Root>
=over 4
=item * $root->get_name();
=item * $root->get_value();
=item * $root->set_value($new_value);
=item * $root->destroy();
=back
=head2 C<::Transaction>
C<ObjectStore> transactions and exceptions are seemlessly integrated into
perl. C<ObjectStore> exceptions cause a C<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: C<read>, C<update>, and
C<abort_only>. The default is C<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.)
=over 4
=item * $T = ObjStore::Transaction::get_current();
=item * $type = $T->get_type();
=item * $pop = $T->get_parent();
=item * $T->prepare_to_commit();
=item * $yes = $T->is_prepare_to_commit_invoked();
=item * $yes = $T->is_prepare_to_commit_completed();
=item * $ObjStore::TRANSACTION_PRIORITY
=item * ObjStore::set_max_retries($oops);
=item * my $oops = ObjStore::get_max_retries();
=item * my $yes = ObjStore::is_lock_contention();
=item * my $type = ObjStore::get_lock_status($ref);
=item * my $tm = ObjStore::lock_timeout($rw);
C<$rw> should be either 'read' or 'write'. Return value of 1 == 1
second. Undef indicates that there is no timeout.
=item * ObjStore::lock_timeout($rw, $tm);
Set lock timeouts.
=back
Dynamic transactions are also available. See L<ObjStore::Serve>.
=head2 C<::Segment>
=over 4
=item * $s->set_comment($comment);
=item * $s->destroy();
=item * $size = $s->size();
=item * $yes = $s->is_empty();
=item * $yes = $s->is_deleted();
=item * $num = $s->get_number();
=item * $comment = $s->get_comment();
=item * $s->lock_into_cache();
=item * $s->unlock_from_cache();
=item * $s->set_fetch_policy($policy[, $size]);
Policy can be one of C<segment>, C<page>, or C<stream>.
=item * $s->set_lock_whole_segment($policy);
Policy can be one of C<as_used>, C<read>, or C<write>.
=back
=head2 C<::Notification>
Easy event dispatching for network distributed objects. See
L<ObjStore::notify>.
=over 4
=item * ObjStore::subscribe(...);
=item * ObjStore::unsubscribe(...);
=item * set_queue_size($size);
=item * ($size, $pending, $overflow) = queue_status();
=item * $fd = _get_fd();
=item * $n = receive([$timeout]);
=item * Receive();
=item * $db = $n->get_database;
=item * $p = $n->focus;
=item * $why = $n->why;
=back
=head2 C<::UNIVERSAL>
All persistent objects inherit from C<ObjStore::UNIVERSAL>.
=over 4
=item * I<overload>
Stringify, boolean & numeric coersion, equality tests.
=item * C<os_class>
Reports the natural persistent class of the object. All persistent
objects must have this class in their C<@ISA> tree.
=item * C<rep_class>
Reports the representation's class.
=item * C<bless>
In addition to the usual meaning of bless, ObjStore C<bless> stores
the current C<@ISA> tree and the C<VERSION> of every member of the
C<@ISA> tree.
=item * C<$o->isa($baseclass)>
Whether the $baseclass was part of the C<@ISA> tree at the moment of
blessing.
=item * C<$o->versionof($baseclass)>
Returns the version of the $baseclass (at the moment of blessing).
=item * C<$o->subscribe()> and C<$o->unsubscribe()>
These might not be available per-object. Only per-segment or
per-database. XXX
=item * C<$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]
=item * Of
C<database_of> and C<segment_of> are available as methods.
=item * C<posh>
C<posh> behavior can be customized by adding special methods that are
detected by C<posh>. See the L<posh> section.
=back
To make everything seem apparently consistent, C<ObjStore::Database>
(while not really being a storable object) is lavishly special-cased
to support most (maybe all!) of the above features.