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
, orstream
.$db->set_lock_whole_segment(policy);
Policy can be one of
as_used
,read
, orwrite
.@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
, orstream
.$s->set_lock_whole_segment($policy);
Policy can be one of
as_used
,read
, orwrite
.
::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 theVERSION
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
andsegment_of
are available as methods.posh
posh
behavior can be customized by adding special methods that are detected byposh
. 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.