YggRep.mesa
Copyright Ó 1988 by Xerox Corporation. All rights reserved.
Bob Hagmann October 28, 1988 10:01:45 am PDT
This interface defines the representation of objects, both in stable and volatile forms
DIRECTORY
Basics USING [charsPerWord, Comparison],
BasicTime USING [GMT],
PBasics USING [UnsafeBlock],
Rope USING [ROPE],
YggDID USING [DID],
YggEnvironment USING [AccessRights, LockOption, nullDID, TransID];
YggRep: CEDAR DEFINITIONS
~ BEGIN
ROPE: TYPE ~ Rope.ROPE;
Volatile object representation
TypedPrimitiveElement: TYPE ~ RECORD [docType: DocType, bits: Bits];
Basic elemental object part, with its type.
DocType: TYPE ~ CARD;
Type of the primitive element.
Reserved document types are 0-65535. Here are some well known types.
unknown: CARD = 0; -- place holder during various operations; never should be seen by clients
int: CARD = 1; -- 32 bit integers
rope: CARD = 2; -- (long null containing) strings
shortRope: CARD = 3; -- strings that are short and null terminated
float: CARD = 4; -- 32 bit floating point
date: CARD = 5; -- GMT date
did: CARD = 6; -- Document Identifier
uninterpretedBytes: CARD = 7; -- (long) byte sequences
lastReservedDocType: CARD = 1023; -- all of types up to and including this one are reserved by the system
Bits: TYPE ~ REF; -- For well known types, Bits is a REF to an INT32, ROPE, REAL32, or YggRep.AccurateGMT, or it is a YggDID.DID. Otherwise it is a REF BitsRep.
BitsRep: TYPE ~ RECORD [
validBytes: CARD,
b: PACKED SEQUENCE length: CARD OF BYTE
];
Uninterpreted bytes of a small object.
BytesFromBits: PROC [bits: Bits, startByte: CARD, block: PBasics.UnsafeBlock];
Fetch some bytes from an "uninterpreted bytes" object.
BitsFromBits: PROC [bits: Bits] RETURNS [copy: Bits];
Copy the Bits to a new Bits object.
SizeOfBits: PROC [bits: Bits] RETURNS [size: CARD];
Size in bytes of an "uninterpreted bytes" object.
SetSizeOfBits: PROC [bits: Bits, size: CARD] RETURNS [newRef: BOOL, newBits: Bits];
Set the size in bytes of an "uninterpreted bytes" object. If this grows the object, the new bytes are uninitalized. This may grow the object and change its representation. All callers must look at the newRef and newBits return values. If newRef is TRUE, then the old bits object is no longer valid. The caller is responsible for updating the data structure from which it obtained the bits.
BytesToBits: PROC [bits: Bits, startByte: CARD, block: PBasics.UnsafeBlock] RETURNS [newRef: BOOL, newBits: Bits];
Store some bytes into an uninterpreted bytes" object. This may grow the object and change its representation. All callers must look at the newRef and newBits return values. If newRef is TRUE, then the old bits object is no longer valid. The caller is responsible for updating the data structure from which it obtained the bits.
AccurateGMT: TYPE ~ REF AccurateGMTRep;
AccurateGMTRep: TYPE ~ RECORD [
gmt: BasicTime.GMT, -- 1968 to 2036 (231 seconds)
usecs: INT32
];
AccurateGMTRepByteSize: INT = WORDS[AccurateGMTRep] * Basics.charsPerWord;
TimeStamp: TYPE = RECORD[
counter: INT ← 0
];
nullTimeStamp: TimeStamp = [0];
NextTimeStamp: PROC [current: YggRep.TimeStamp] RETURNS [next: YggRep.TimeStamp];
MaxTimeStamp: PROC [ts1: YggRep.TimeStamp, ts2: YggRep.TimeStamp] RETURNS [maxTS: YggRep.TimeStamp];
CompareTimeStamps: PROC [ts1: YggRep.TimeStamp, ts2: YggRep.TimeStamp] RETURNS [Basics.Comparison];
VDoc: TYPE ~ REF VDocRep;
VDocRep: TYPE ~ RECORD [
did: YggDID.DID, -- document identifier for the document
tid: YggEnvironment.TransID, -- transactional view of the document
latched: BOOLFALSE,
for links, the next three fields have non-trivial values
fromDID: YggDID.DID ← YggEnvironment.nullDID,
toDID: YggDID.DID ← YggEnvironment.nullDID,
linkType: Rope.ROPENIL,
linkChanged: BOOL ← FALSE,
contents: TypedPrimitiveElement ← [unknown, NIL],
contentsChanged: BOOLFALSE,
outlinks: LIST OF AttributeValue ← NIL, -- the outlinks of the document
outlinksChanged: LIST OF linkMod ← NIL, -- changes to the outlinks
inlinks: LIST OF AttributeValue ← NIL, -- the inlinks of the document
inlinksChanged: LIST OF linkMod ← NIL, -- changes to the inlinks
attributes: LIST OF Attribute ← NIL, -- the attributes of the document
namesOfAttributesChanged: LIST OF ROPENIL, -- the names of attribute(s) changed, NIL if none
attributesChanged: LIST OF Attribute ← NIL, -- the attribute(s) changed, NIL if none
metaAttributes: LIST OF Attribute ← NIL, -- the meta attributes of the document (indices, parents, children, ...)
metaAttributesChanged: LIST OF metaAttributeMod ← NIL -- mod(s) to the meta attribute(s), NIL if none
];
the volatile representation of an object
linkMod: TYPE ~ RECORD [
add: BOOL, -- TRUE => add link, FALSE => delete link
linkName: ROPE, -- name of the link type
linkValue: YggDID.DID -- DID for link (not the DID of the linked-to document)
];
Attribute: TYPE ~ RECORD [
attributeName: ROPE, -- name of the attribute (not unique for a given document)
ordered: BOOL, -- whether the the valueSet is ordered
value: LIST OF AttributeValue -- set of values for attribute
];
An attribute for an object.
nullAttribute: Attribute = [NIL, FALSE, NIL];
AttributeValue: TYPE ~ RECORD [
fieldName: ROPE, -- name of the attribute (not unique for a given document)
valueSet: LIST OF TypedPrimitiveElement -- set of values for field
];
nullAttributeValue: AttributeValue = [NIL, NIL];
metaAttributeMod: TYPE ~ RECORD [
attributeName: ROPE, -- name of the meta attribute (e. g., $parents)
add: BOOL, -- TRUE => add attribute or modify existing value, FALSE => delete attribute
didValue: YggDID.DID, -- DID (if appropiate)
stringValue: ROPE -- value for rope (if appropiate)
];
VolatizeFromDID: PROC [transID: YggEnvironment.TransID, did: YggDID.DID, access: YggEnvironment.AccessRights ← readOnly, lock: YggEnvironment.LockOption ← [read, wait], metaAttributesOnly: BOOLFALSE] RETURNS [vDoc: VDoc];
Given a DID, return the volatile form of the document it refers to. If metaAttributesOnly is TRUE, then the transID must be null.
LatchVDoc: PROC [vDoc: VDoc, wait: BOOLTRUE] RETURNS [latched: BOOL];
Set a short term latch.
UnlatchVDoc: PROC [vDoc: VDoc] RETURNS [latched: BOOL];
Remove a short term latch.
Transactions
PreCommit: PROC[tid: YggEnvironment.TransID];
Commit: PROC[tid: YggEnvironment.TransID];
Abort: PROC[tid: YggEnvironment.TransID];
Attribute coding
Attributes are written to a stream by following this algorithm.
Write the type of the contents.
Do for all attributes:
Write a preamble byte.
bit meaning
0 0 = ordered
1 0 = no field names
2 0 = singleton attribute value (i. e., there is only one field)
3 0 = singleton field value(s) (i. e., every field has only one value)
4-6 code for type of data
 0 - each one is separate
 1 - integer (32 bit)
 2 - rope (may be large and contain nulls)
 3 - rope (shorter and null terminated)
 4 - float (32 bit)
 5 - date (GMT)
 6 - DID Document Identifier (see YggDID.DID)
 7 - uninterpreted bytes
7 to be defined
Write the attribute name. It starts at byte 1, fills to an integral number of words and is null ('0C) terminated. Unused bytes are null filled.
If there isn't a singleton attribute value, then write the number of attributes in a word.
For each attribute:
If there isn't a singleton field value, then write the number of fields in a word.
For each field:
If there is a field name, or the field name is NIL but no field names is not set, then write the field name. It starts at byte 0, fills to an integral number of words and is null ('0C) terminated. Unused bytes are null filled.
For each field value:
If the code for type of data is each one is seperate, then write the type word.
Write the type value:
integers take a 32 bit word
rope (may be large and contain nulls) is preceeded by a size word
rope (shorter and null terminated) fills to an integral number of words and is null ('0C) terminated. Unused bytes are null filled.
floats take a 32 bit word
dates takes a 32 bit word
everything else is bits: write a 32 bit size field and the bits, null fill if necessary
charsPerWord: CARD ~ BITS[WORD]/8;
AttributePreamble: TYPE ~ PACKED ARRAY [0..charsPerWord) OF AttributePreambleByte;
use this to generate a pointer to a AttributePreambleByte; { apb: AttributePreambleByte; ... @apb ... } is wrong!
AttributePreambleByte: TYPE ~ MACHINE DEPENDENT RECORD [
ordered (0:0..0): BOOLFALSE, -- true if the attribute values are ordered
noFieldNames (0:1..1): BOOLFALSE, -- true if there are no field names
singletonAttribute (0:2..2): BOOLFALSE, -- true if there is only one field in the attribute
singletonField (0:3..3): BOOLFALSE, -- true if there is only one value in each of the fields
typeCode (0:4..6): AttributePreambleType ← separate, -- code for type of data
spare (0:7..7): BOOLFALSE
];
Preamble byte for each attribute.
AttributePreambleType: TYPE ~ MACHINE DEPENDENT { separate (0), integer (1), ropeLarge (2), ropeShort (3), float (4), date (5), did (6), uninterpretedBytes (7)};
Information about the attribute.
END.