/ 
ObjStore-1.06
River stage zero No dependents
/ ObjStore

NAME

ObjStore - Perl extension for ObjectStore ODMS

SYNOPSIS

  use ObjStore;

  $osdir = ObjStore->schema_dir;
  my $DB = ObjStore::Database->open($osdir . "/perltest.db", 0, 0666);

  try_update {
      my $top = $DB->root('whiteboard');
      if ($top) {
	  print "Very impressive.  I see you are already an expert.\n";
	  exit;
      }
      $top = $DB->root('whiteboard', $DB->newHV('dict'));
      for (my $x=1; $x < 1000000000; $x++) {
	  $top->{$x} = {
	      id => $x,
	      m1 => "I will not talk in ObjectStore/Perl class.",
	      m2 => "I will study the documentation before asking questions.",
	  };
      }
  };
  print "[Abort] $@\n" if $@;

DESCRIPTION

The new SQL of the late 1990s. The end of relational databases.

OBJECTSTORE PHILOSOPHY

ObjectStore is outrageously powerful and sophisticated. It actually does way too much for the average get-the-job-done programmer. The theme of this interface for ObjectStore is simplicity and easy of use. The performance of raw ObjectStore is so good that even with a gunky Perl layer, benchmarks will find relational databases left on the bookshelf.

Specifically, the interface is optimized for flexibility, then memory performance, then speed. If you really want speed, wait till Perl5 gets access to pthreads. Or see the TODO list about dynamic linking additional C++ objects.

TRANSACTIONS

1. You cannot access or modify persistent data outside of a transaction.

    {
	my $var;
	try_update {
	    $var = $DB->root('top');
	};
	$var->{foo} = 2;      # $var usage causes ObjStore exception
    }

2. It is impractical to use read_only transactions because collections include embedded cursors. You cannot iterate over collections without modifying the cursors in the database. This should be construed as a bug in the Perl core. As a work-around, read transactions are implemented with the abort_only transaction mode. This mode allows you to modify the database but will not commit the changes. However, you should not assume that read transactions will always be implemented with abort_only.

REFERENCE COUNTING

It is not practical to simply make perl types persistent. Values in the database have different requirements than transient values and require a custom solution.

1. All data allocated in the database is reference counted separately from transient data.

2. You cannot take a reference to a persistent scalar value. Is there a good reason to allow this?

CONTAINERS

There are a few considerations when creating a container: which segment, which symantics, and which implementation.

HASHES

my $h1 = $store->newTiedHV('array');
$h1->{abc} = 3;

my $h2 = $store->newTiedHV('dict');
$h2->{def} = 3;

Array implementations have one caveat: if they need to resize, any transient references you might have around will become pointers to random memory. This case actually doesn''t come up very often. To mess up, you need to go through these contortions:

my $top = $DB->newTiedHV('array');
my $dict = $top->{dict} = $DB->newHV('dict');
for (1..14) { $top->{$_} = $_; }   # force resize of $top

$dict->{foo} = 'bar';              # $dict points to random OOPS!

$dict = $top->{dict};              # now $dict OK
$dict->{foo} = 'bar';              # OK

SACKS

$store->newSack('array');

Sacks are sequential access containers. They support the following methods:

void $sack->a($element);
void $sack->r($element);
int  $sack->contains($element);
SV*  $sack->first();
SV*  $sack->next();
void $sack->bless('classname');

Not very feature-ful, are they? You''d think you would get a big efficiency win! In fact, they are only a little better than hashes. Sacks are really just a stop-gap until Larry and friends figure out how to do tied arrays.

AUTHOR

Joshua Pritikin, pritikin@mindspring.com

SEE ALSO

Perl documentation, ObjectStore documentation