VoiceRopeDBImpl.mesa
Copyright © 1986 by Xerox Corporation. All rights reserved.
Doug Terry, June 3, 1986 5:28:55 pm PDT
Routines for storing voice ropes in a database and manipulating their structure.
It is unresolved where a tune's encryption key should be stored. For now, it is kept with the tune interval; though this is the wrong place. It should probably be kept in the tune's header. Can't do that since FinchSmarts wants to be passed the key.
DIRECTORY
BasicTime USING [earliestGMT, Now, Period],
Convert USING [IntFromRope, RopeFromInt],
IO USING [card, GetCard, GetInt, int, PutFR, RIS, rope, STREAM],
LoganBerryStub USING [AttributeType, AttributeValue, Entry, Error, ErrorCode, Open, OpenDB, ReadEntry, WriteEntry],
Rope USING [Concat, ROPE],
Thrush USING [EncryptionKey, Tune, VoiceInterval],
UserCredentials USING [CredentialsChangeProc, Get, RegisterForChange],
VoiceRopeDB;
VoiceRopeDBImpl: CEDAR PROGRAM -- Should this be a monitor?
IMPORTS BasicTime, Convert, IO, Rope, UserCredentials, LoganBerry: LoganBerryStub
EXPORTS VoiceRopeDB
~
BEGIN
OPEN VoiceRopeDB;
ROPE: TYPE ~ Rope.ROPE;
STREAM: TYPE ~ IO.STREAM;
Database operations
Voice ropes are stored in a LoganBerry database as a header followed by a list of tune intervals (a TuneList). Interests in voice ropes are also maintained in a LoganBerry database.
Open:
PUBLIC PROC[dbName: Rope.
ROPE]
RETURNS [handle: Handle ←
NIL, openEc: LoganBerry.ErrorCode ←
NIL, expl: Rope.
ROPE] = {
ENABLE LoganBerry.Error => { openEc ← ec; expl ← explanation; CONTINUE; };
handle ← NEW[HandleRec ← [voiceRopeDBName: dbName.Concat[".df"], voiceInterestDBName: dbName.Concat["Refs.df"]]];
handle.voiceRopeDB ← LoganBerry.Open[dbName: handle.voiceRopeDBName];
handle.voiceInterestDB ← LoganBerry.Open[dbName: handle.voiceInterestDBName];
};
Read:
PUBLIC
PROC [handle: Handle, ropeID:
ID]
RETURNS [header: Header, length:
INT, struct: TuneList] ~ {
Returns the structure of the given voice rope.
header ← LoganBerry.ReadEntry[db: handle.voiceRopeDB, key: $VRID, value: ropeID].entry;
[length, struct] ← EntryToTuneList[header];
};
Write:
PUBLIC PROC [handle: Handle, struct: TuneList]
RETURNS [ropeID: ID, length:
INT] ~ {
Writes the voice rope information into the LoganBerry database.
entry: LoganBerry.Entry;
interval: Thrush.VoiceInterval;
compute length of voice rope
list: TuneList ← struct;
length ← 0;
UNTIL list =
NIL
DO
[interval: interval, rest: list] ← NextTuneOnList[list];
length ← length + interval.length;
ENDLOOP;
ropeID ← GenerateUniqueID[];
entry ← struct;
entry ← CONS[[$Length, Convert.RopeFromInt[length]], entry];
will have to change how we get creator across RPC connection.
entry ← CONS[[$Creator, UserCredentials.Get[].name], entry];
entry ← CONS[[$VRID, ropeID], entry];
LoganBerry.WriteEntry[db: handle.voiceRopeDB, entry: entry ! LoganBerry.Error => IF ec = $ValueNotUnique THEN {ropeID ← BadUniqueID[]; entry.first.value ← ropeID; RETRY}];
};
Voice rope structure
A tune list, the structure of a voice rope, is represented in a LoganBerry database as an ordered list of $TID (the tune's ID), $Key (the tune's encryption key), and $SL (the start and length of a tune interval) attributes. The tune's encryption key should probably be kept in the tune's header, but that can't be done if FinchSmarts is used to record and play tunes.
SimpleTuneList:
PUBLIC PROC [tune: Thrush.Tune, interval: Thrush.VoiceInterval, key: Thrush.EncryptionKey]
RETURNS [list: TuneList] ~ {
Builds a tune list with a single tune's information.
list ← LIST[[$TID, Convert.RopeFromInt[tune]], [$Key, MarshalKey[key]], [$SL, MarshalInterval[interval]]];
};
NextTuneOnList:
PUBLIC PROC [list: TuneList]
RETURNS [tune: Thrush.Tune, interval: Thrush.VoiceInterval, key: Thrush.EncryptionKey, rest: TuneList] ~ {
Returns information about the next tune on the list; assumes that list really points to a properly structured TuneList so doesn't bother to check attribute types. The rest of the list is returned so this routine can be repetitively called to get all the tunes on the list.
tune ← Convert.IntFromRope[list.first.value];
key ← UnmarshalKey[list.rest.first.value];
interval ← UnmarshalInterval[list.rest.rest.first.value];
rest ← list.rest.rest.rest;
};
EntryToTuneList:
PROC [entry: LoganBerry.Entry]
RETURNS [length:
INT ← -1, struct: TuneList] ~ {
Returns the tune list representing the structure of the voice rope.
IF entry = NIL THEN RETURN[struct: NIL];
UNTIL entry.first.type = $TID
DO
IF entry.first.type = $LENGTH
THEN
length ← Convert.IntFromRope[entry.first.value];
entry ← entry.rest;
ENDLOOP;
struct ← entry;
};
TuneListInterval:
PUBLIC PROC [list: TuneList, interval: Thrush.VoiceInterval]
RETURNS [new: TuneList] ~ {
Returns the tune list representing the structure of the voice rope interval. Warning: this operation modifies the original list!
tuneInterval: Thrush.VoiceInterval; -- the current tune's interval
prevSamples: INT; -- number of samples in entry excluding the current tune interval
samples: INT; -- number of samples in entry including the current tune interval
intervalMustChange: BOOLEAN ← FALSE;
prevSamples ← 0;
tuneInterval ← UnmarshalInterval[list.rest.rest.first.value];
samples ← tuneInterval.length;
UNTIL samples > interval.start
DO
prevSamples ← samples;
list ← list.rest.rest.rest;
IF list = NIL THEN RETURN[NIL];
tuneInterval ← UnmarshalInterval[list.rest.rest.first.value];
samples ← samples + tuneInterval.length;
ENDLOOP;
at this point: prevSamples <= interval.start < samples
new ← list;
IF prevSamples # interval.start
THEN {
-- don't want first part of existing interval
tuneInterval.start ← tuneInterval.start + interval.start - prevSamples;
tuneInterval.length ← tuneInterval.length - (interval.start - prevSamples);
intervalMustChange ← TRUE;
};
Note: there's a possibility that interval.start + interval.length could cause an integer overflow; do I want to pay the cost to check for this?
IF (interval.length #
LAST[
INT])
AND (samples >= interval.start + interval.length)
THEN {
-- interval contained within a single tune interval
tuneInterval.length ← interval.length;
list.rest.rest.rest ← NIL; -- truncate list since we have has much as we need
intervalMustChange ← TRUE;
};
IF intervalMustChange
THEN
new.rest.rest.first.value ← MarshalInterval[tuneInterval];
IF (interval.length =
LAST[
INT])
OR (samples >= interval.start + interval.length)
THEN
-- no need to go on
RETURN[new];
UNTIL samples >= interval.start + interval.length
DO
prevSamples ← samples;
list ← list.rest.rest.rest;
IF list = NIL THEN RETURN[new];
tuneInterval ← UnmarshalInterval[list.rest.rest.first.value];
samples ← samples + tuneInterval.length;
ENDLOOP;
at this point: prevSamples <= interval.start + interval.length <= samples
IF samples # interval.start + interval.length
THEN {
-- want only first part of tune interval
list.rest.rest.first.value ← MarshalInterval[[start: tuneInterval.start, length: interval.start + interval.length - prevSamples]];
};
list.rest.rest.rest ← NIL; -- truncate list since we have has much as we need
RETURN[new];
};
Conversions (marshalling)
MarshalKey:
PROC [key: Thrush.EncryptionKey]
RETURNS [r:
ROPE] ~
TRUSTED {
cardKey: LONG POINTER TO ARRAY[0..2) OF LONG CARDINAL=LOOPHOLE [LONG[@key]];
r ← IO.PutFR["%bB %bB", IO.card[cardKey[0]], IO.card[cardKey[1]]];
};
UnmarshalKey:
PROC [r:
ROPE]
RETURNS [key: Thrush.EncryptionKey] ~
TRUSTED {
cardKey: LONG POINTER TO ARRAY[0..2) OF LONG CARDINAL=LOOPHOLE[LONG[@key]];
keyStream: IO.STREAM ← IO.RIS[r];
cardKey[0] ← IO.GetCard[keyStream];
cardKey[1] ← IO.GetCard[keyStream];
};
MarshalInterval:
PROC [interval: Thrush.VoiceInterval]
RETURNS [r:
ROPE] ~
INLINE {
Writes a start and length field into a rope.
r ← IO.PutFR["%g %g", IO.int[interval.start], IO.int[interval.length]];
};
UnmarshalInterval:
PROC [r:
ROPE]
RETURNS [interval: Thrush.VoiceInterval] ~
INLINE {
Parses the input rope into a start and length field.
s: IO.STREAM ← IO.RIS[r];
interval.start ← IO.GetInt[s];
interval.length ← IO.GetInt[s];
};
Generating unique identifiers
A unique identifier is generated by concatenating a user's Rname with a timestamp. This assumes that the same user is not simultaneously creating voice ropes from two different workstations. This problem would not arise if machine names were used instead of user names. The technique used for obtaining the user's name will have to change when this code runs on the voice server instead of on client machines.
The timestamp is taken to be the maximum of the current time (converted to an integer) and a simple counter. The current time alone is not sufficient since it has a granularity of seconds. Several voice ropes may be created within a second, but the long-term creation rate should be much less than one per second. The counter is initialized to the current time, which could cause some problems if this module is rerun before the current time has a chance to catch up to the old counter (or if a machine's clock is reset to an earlier time). This problem is detected by $ValueNotUnique errors from LoganBerry when one attempts to write a new voice rope.
Note that the counter, as maintain by these routines, is sufficient as a unique ID if this code is run on the voice server. However, having a user's name and current timestamp as part of the permanent voice rope ID provides information that might be useful.
userName: ROPE;
counter: INT;
kicks: INT; -- for instrumentation purposes
GenerateUniqueID:
PROC []
RETURNS [id:
ROPE] ~ {
timestamp: INT ← MAX[counter, BasicTime.Period[BasicTime.earliestGMT, BasicTime.Now[]]];
id ← IO.PutFR["%g#%g", IO.rope[userName], IO.int[timestamp]];
counter ← counter + 1;
};
BadUniqueID:
PROC []
RETURNS [id:
ROPE] ~ {
This routine should be called if some generated ID does not turn out to be unique. It trys once again to generate a unique ID after advancing the counter.
counter ← BasicTime.Period[BasicTime.earliestGMT, BasicTime.Now[]]+1; -- kick the counter
kicks ← kicks + 1;
id ← GenerateUniqueID[];
};
NewUser: UserCredentials.CredentialsChangeProc ~ {
userName ← UserCredentials.Get[].name;
};
InitUniqueID:
PROC []
RETURNS [] ~ {
counter ← BasicTime.Period[BasicTime.earliestGMT, BasicTime.Now[]];
kicks ← 0;
userName ← UserCredentials.Get[].name;
UserCredentials.RegisterForChange[NewUser];
};
Initializations
InitUniqueID[];
END.
Doug Terry, June 3, 1986 4:19:14 pm PDT
Extracted database operations from VoiceRopeImpl.mesa.
changes to: VoiceRopeDBImpl , EXPORTS , ~ , WriteVoiceRope
Doug Terry, June 3, 1986 5:23:23 pm PDT
changes to: VoiceRopeDBImpl, EXPORTS, ~, Open, WriteVoiceRope, END, DIRECTORY, IMPORTS, Read, SimpleTuneList, NextTuneOnList, TuneListInterval, EntryToTuneList