ObjStore::Reference - a listing of APIs
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.
ObjectStore
C++
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.
::UNIVERSAL
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
$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.
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.
segment
page
stream
$db->set_lock_whole_segment(policy);
Policy can be one of as_used, read, or write.
as_used
read
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.
die
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.
update
abort_only
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.
$rw
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]);
$s->set_lock_whole_segment($policy);
::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;
All persistent objects inherit from ObjStore::UNIVERSAL.
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.
@ISA
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.
VERSION
$o-isa($baseclass)>
$o-
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.
database_of
segment_of
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.
ObjStore::Database
To install ObjStore, copy and paste the appropriate command in to your terminal.
cpanm
cpanm ObjStore
CPAN shell
perl -MCPAN -e shell install ObjStore
For more information on module installation, please visit the detailed CPAN module installation guide.