-- file: NuthatchPrimitives.txt
-- old description of nuthatch procedures; no longer matches source file
-- Last edited by Lia September 30, 1983 3:17 pm


Nuthatch provides a file directory system for voice files.  The directory is organized as a Cypress database, with two main 
relations.  They are the voiceReferences relation, which stores information such as the creator, length, and structure of the voice 
file; and the InterestList relation, which maintains reference count informaton, so that voice files that have no more users 
interested in them can be garbage collected.  There are four Nuthatch operations to update these relations.  One creates an entry 
in the voice file directory, with defaults for the expiration date.  The others update information about the voice file's 
expiration date, which users have references to the voice file, and by what means they have one (e.g. by having a voice attachment 
to a Walnut message, or a voice-annotated Tioga document, or a recorded phone call). 

Updates are performed by an updating process that reads entries in a user's Nuthatch log and uses them to update the voice file 
directory.  Because the directory is a Cypress database, these updates are done as an atomic transaction, under the user 
application's control.
     
There are four types of log entries: (Send, Incr, Decr)

Catalog Voice File:
    voiceMessageID,
    creator, 
    startingSample,
    samples, 
    type,
    expirationDate,
    type,
    encryptionKey, 
    time

Create Interest List Entry:
    voiceMessageID,
     RefIDType, 
     RefID,
    holder, 

Incr:
    voiceMessageID,
    RefIDType and RefID,
    holder, 
    time of log entry

Decr:
    voiceMessageID,
    RefIDType and RefID,
    holder, 
    time of log entry


Transactions

An application program manipulating voice files uses Nuthatch by writing Nuthatch log entries.  Nuthatch processes logs in the 
following way :

open log for writing;
    
for each entry:
    begin trans
    get the current read-point from the log;
    perform the appropriate update on the DB for this entry (requires write lock)
    write the new read-point in the log
    end trans
    

Nuthatch Primitives

The procedural interface to Nuthatch are in Nuthatch.mesa: