LoganBerry is a simple facility for managing databases. It allows various types of data to be stored persistently and be retrieved by key or key subrange. Data is stored in one or more log files and indexed using stable btrees. A database survives processor crashes, but the data management facility does not provide atomic transactions. Databases may be shared by multiple clients and accessed remotely via RPC.

To get started in Cedar on a Dorado, bringover [CedarChest®]<Top>LoganBerry.df. Clients should install LoganBerry. Additionally, clients that want access to remote databases should install LoganBerryStub, LoganBerryCourierStub, and/or LoganBerrySunStub. These can be installed at any time in any order. Installing LoganBerryMultiStub loads all three stubs.

To get started in PCedar on a Sun, you do not have to do any bringovers or anything. Clients should simply put "Require PCedar LoganBerry LoganBerry" in their .require file. Additionally, clients that want access to remote databases should "Require PCedar LoganBerry LoganBerrySunStub".

LoganBerry.mesa contains definitions for the basic data types and operations. This interface is the main one used by LoganBerry client programs. LoganBerryEntry.mesa contains some useful utilities for manipulating LoganBerry entries. LoganBerry supports three additional interfaces. LoganBerryExtras.mesa allows one to register procedures, or "triggers", that get called when a database is updated. These have been used to build in-memory LoganBerry caches, for example. LoganBerryBackdoor.mesa exports some useful log-management and entry-management procedures. LoganBerryClass.mesa allows one to register new LoganBerry implementations (as explained below). These last three interfaces are for use by database maintainers or application specialists, and should not be needed by ordinary clients.

Additional tools, such as the LoganBerry browser as well as more complex query facilities, can be found in [CedarChest®]<Top>LoganBerryTools.df for DCedar or /PCedar/Top/LoganBerryTools-Suite.df for PCedar. LoganBerryTools also includes some useful commands for dealing with LoganBerry databases. See LoganBerryToolsDoc.Tioga.

For some databases, there may be no natural attribute to serve as a key. In this case, a unique timestamp can be used as a key. LoganBerryEntry.NewTimestamp generates a timestamp that is close to the current time and such that subsequent calls to NewTimestamp yield different results provided (1) the calls are performed on the same machine, and (2) the machine has not crashed and been restarted in between calls. Even if NewTimestamp is called on different machines, the results will be unique with a high probability.

Timestamps generated by calls to NewTimestamp may be used directly as keys as in the following piece of code:

Mechanisms exist for registering new LoganBerry classes (see LoganBerryClass.mesa). A LoganBerry class is a collection of routines that implement the LoganBerry interface. In addition to the standard LoganBerry implementation, examples of LoganBerry classes include stubs for performing RPC calls to remote LoganBerry servers and "veneers" that enable other databases, such as Cypress, to be accessed as LoganBerry databases. New classes can be registered at any time in any order. All registered classes are accessed through the same LoganBerry interface.

A specific class is bound to a database handle during the Open call. On Open, each registered LoganBerry class is given the opportunity to Open the named database. The first class that returns a non-null open database handle is used for subsequent calls on that handle. Thus, the Open routine for each class should first check that the named database is one that is managed by the particular class. If it can't handle the named database then it should return LoganBerry.nullDB. If the database name is one that is manged by this class but the database can not be successfully opened for some reason, then the Open procedure should raise an Error.

One particularly useful class, included automatically with LoganBerry, intercepts ordinary LoganBerry calls to provide an in-memory cache of LoganBerry entries. For applications that read the same entries repeatedly, performance can be considerably improved by using an entry cache.

This cache resides on the client machine issuing the calls, not on the server containing the persistent copy of the database. It is therefore dangerous to use (not guaranteed to be up to date) when another client might be updating the database concurrently. It also provides cached access only for ReadEntry queries requesting a complete match on the primary key: secondary key accesses and accesses through the pattern enumeration operations do not use the cache.

The implementation uses the same Error instance as LoganBerry does to raises its own LoganBerry errors; it also lets most of the real ones through. This may sometimes be confusing, since the DB in effect at the time may be different.

Some of the more exotic features of LoganBerry, such as the ability to specify specific logs for individual writes, may not work properly when an entry cache is used. The client programmer must use judgement, tempered by consultation with the implementors, before enabling caching on a database.

The cache implementation is willing to do non-write-through caching of entries. That is, WriteEntry calls store the changed entry only in the cache, deferring the actual database update until a later time. This feature is supported only for those who have consulted the author(s). Non-write-through caching, which is enabled separately, is of limited value: any attempt to access entries through any key other than the primary one while non-write-through caching is asserted, or any concurrent attempts to write new entries, are fraught with peril. Also, many operations, such as entry deletion, will not work properly when database update is deferred in this way. The mechanism was created to improve the performance of a batch database creation process where, with performance further enhanced by the use of LoganBerry transactions, many entries are written several times before the process completes; deferring the writes reduces the total time and space required to log the entries each time.

Whenever the caching class is loaded (it is present in the standard LoganBerry configuration), its use can be requested by appending the suffix "-cached" to the name of the schema file in a LoganBerry Open operation. Databases opened using file name specifications that do not contain the suffix will use the ordinary local or remote LoganBerry class. However, the cache will only be maintained, and ReadEntry requests will only honor the cache contents, when LoganBerry caching is enabled by the commands below. When the feature is disabled, all requests will simply be passed on to the underlying persistent databases.

Philosophy: Preserve the original code as much as possible and change where absolutely necessary to maintain the same semantics.

Replaced occurrences of GeneralFS and FS with UFS. The convention I followed is to bracket the old FS (GeneralFS) statement with << >> and turn it into a comment. The new statement either precedes or succeeds the old statement. There are two changes worth mentioning. First, the only way files are opened is through UFS.StreamOpen in either read, write, or create mode. Second, log files are not now ever opened in append mode, only in write mode. In the old code, a file opened in append mode was mostly being used as if it had been opened in write mode.

File creation time problem: When a file is opened in either $write or $create mode, the file creation time is updated but doesn't change even when writing to it until the file is opened again (after being closed). In Unix, the create date (mtime) is continually updated as the file is written to. I worried about this because IndicesOutOfDate assumes the former. Added a new data structure LogCreateDate to remember the time the file is opened and a routine SetCreateTime to reset the file mtime when the file is closed. This is a hack to preserve the semantics the client sees and to avoid making incompatible changes. A better approach in the long run is to timestamp the file as a comment. This stuff is part of LoganBerryImpl so as to avoid changing UFSImpl's interface.

Compacting logs: Beware!! The old code assumes the existence of versions, so you never need to worry about clobbering the old log files. Not so under Unix. There's now a window of vulnerability during which the old log file can be completely clobbered while the bits from the compacted log are being copied. Since UFS hasn't implemented a Rename routine, I used UFS.Copy followed by UFS.Delete: Copy will copy the new bits to the old name, and Delete will delete the temporary file. If the system crashes during the copy, the old log will be clobbered and lost. If there's a way to do this atomically, someone let me know. (Peter Kessler says that DFS handles versions. Rather than using yet another file system, I'll wait until PFS becomes available.)

BTreeSimple interface change: used Russ Atkinson's changes to BTreeVMImpl as the basis.

Removed all the RPC multi-stub stuff since they're mostly not portable and kept the Sun RPC stuff. Sun RPC hasn't been tested yet. Bill Jackson is doing that. Hence, it is not possible to call LoganBerry operations remotely. For the moment, RPC.conversation is just a CARD32 type.

Michael Plass pointed out some problems with binary data: If you store data containing a CR, it gets stored in a rope literal as "\n". In the PCedar world, this would get read as LF, which is OK if it is really used as a newline, but if it is really binary data, it means trouble. LoganBerry (or maybe IO) should emit "\r" or "\015" to keep the bits unambiguous. These changes have been incorporated.