PFSClass.mesa
Copyright Ó 1989, 1990, 1991, 1992 by Xerox Corporation. All rights reserved.
Doug Wyatt, February 2, 1990 4:24:56 pm PST
Chauser, March 20, 1992 1:42 pm PST
Willie-s, September 4, 1991 3:01 pm PDT
Michael Plass, January 27, 1992 5:11 pm PST
DIRECTORY
IO USING [STREAM],
PFS,
PFSNames USING [PATH, Version],
Rope USING [ROPE]
;
PFSClass: CEDAR DEFINITIONS
~ {
Introduction
PFSClass defines a registration mechanism for file system view implementations to hook themselves up to PFS.
In keeping with PFS's philosophy regarding Errors and monitor locks, a class should never raise an error while holding a lock: clients are entitled to call other procedures in the class during error handline.
Copied Types
ROPE: TYPE ~ Rope.ROPE;
PATH: TYPE ~ PFSNames.PATH;
Version: TYPE ~ PFSNames.Version;
UniqueID: TYPE ~ PFS.UniqueID;
Types
OpenFile: TYPE = REF OpenFileObject;
OpenFileObject: TYPE = RECORD [
fs: FSHandle,
fullFName: PATH,
attachedTo: PATH,
uniqueID: PFS.UniqueID,
bytes: INT,
mutability: PFS.Mutability,
fileType: PFS.FileType,
access: PFS.AccessOptions,
state: {closed, open},
data: REF
];
FS handles
note: as an abbreviation "FS" is to be read "File System"
FSHandle: TYPE ~ REF FSObject;
FSObject: TYPE ~ RECORD [
flavor: ATOM,
name: ROPE, -- e.g. "Ivy-STP", "Palain-NFS"
maintenanceProcs: MaintenanceProcs,
procs: FileManipulationProcs,
data: REF
];
MaintenanceProcs: TYPE ~ REF MaintenanceProcsObject;
MaintenanceProcsObject: TYPE ~ RECORD [
sweep: SweepProc ¬ NIL,
validate: ValidateProc
];
FileManipulationProcs: TYPE = REF FileManipulationProcsObject;
FileManipulationProcsObject: TYPE = RECORD [
delete: DeleteProc,
enumerateForInfo: EnumerateForInfoProc,
enumerateForNames: EnumerateForNamesProc,
fileInfo: FileInfoProc,
lookupName: LookupNameProc,
rename: RenameProc,
copy: CopyProc,
setAttributes: SetAttributesProc,
setByteCountAndUniqueID: SetByteCountAndUniqueIDProc,
setClientProperty: SetClientPropertyProc,
getClientProperty: GetClientPropertyProc,
enumerateClientProperties: EnumerateClientPropertiesProc,
read: ReadProc,
write: WriteProc,
open: OpenProc,
close: CloseProc,
store: StoreProc,
retrieve: RetrieveProc,
attach: AttachProc,
getInfo: GetInfoProc,
pfsNameToUnixName: PFSNameToUnixNameProc,
caseSensitive: CaseSensitiveProc
];
Types for procedures each class should implement
By convention, the PATH arguments that are passed by PFSImpl to the class implementations of these procedures have an empty 0th component (corresponding to the class designation). The class information is captured at this level in the FSHandle.
LookupNameProc: TYPE = PROCEDURE [h: FSHandle, file: PATH] RETURNS[PATH];
DeleteProc: TYPE = PROCEDURE [h: FSHandle, file: PATH, wantedUniqueID: UniqueID, proc: PFS.NameConfirmProc];
EnumerateForInfoProc: TYPE = PROCEDURE [h: FSHandle, pattern: PATH, proc: PFS.InfoProc, lbound: PATH, hbound: PATH];
EnumerateForNamesProc: TYPE = PROCEDURE [h: FSHandle, pattern: PATH, proc: PFS.NameProc, lbound: PATH, hbound: PATH];
FileInfoProc: TYPE = PROCEDURE [h: FSHandle, file: PATH, wantedUniqueID: UniqueID]
RETURNS [version: Version, attachedTo: PATH, bytes: INT, uniqueID: UniqueID,
mutability: PFS.Mutability, fileType: PFS.FileType];
RenameProc: TYPE = PROCEDURE [h: FSHandle, fromFile: PATH, wantedUniqueID: UniqueID, toFile: PATH, createOptions: PFS.CreateOptions, proc: PFS.NameConfirmProc]
RETURNS [done: BOOL ¬ FALSE];
CopyProc: TYPE = PROCEDURE [h: FSHandle, fromFile: PATH, wantedUniqueID: UniqueID, toFile: PATH, createOptions: PFS.CreateOptions, proc: PFS.NameConfirmProc]
RETURNS [done: BOOL ¬ FALSE];
SetAttributesProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, attributes: PFS.CreateOptions];
SetByteCountAndUniqueIDProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, bytes: INT, uniqueID: PFS.UniqueID];
SetClientPropertyProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, propertyName: ROPE, propertyValue: ROPE];
GetClientPropertyProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, propertyName: ROPE] RETURNS [propertyValue: ROPE];
EnumerateClientPropertiesProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, proc: PFS.PropProc];
OpenProc: TYPE = PROCEDURE [h: FSHandle, file: PATH, wantedUniqueID: UniqueID, access: PFS.AccessOptions, checkFileType: BOOL, fileType: PFS.FileType, createOptions: PFS.CreateOptions]
RETURNS [OpenFile];
ReadProc: TYPE = UNSAFE PROCEDURE [h: FSHandle, file: OpenFile, filePosition, nBytes: CARD, toPtr: LONG POINTER, toStart: CARD]
RETURNS [bytesRead: INT];
WriteProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, filePosition, nBytes: CARD, fromPtr: LONG POINTER, fromStart: CARD]
RETURNS [bytesWritten: INT];
CloseProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile, abort: BOOL];
StoreProc: TYPE = PROCEDURE [h: FSHandle, file: PATH, wantedUniqueID: UniqueID, str: IO.STREAM, proc: PFS.StoreConfirmProc, createOptions: PFS.CreateOptions];
RetrieveProc: TYPE = PROCEDURE [h: FSHandle, file: PATH, wantedUniqueID: UniqueID, proc: PFS.RetrieveConfirmProc, checkFileType: BOOL ¬ FALSE, fileType: PFS.FileType];
AttachProc: TYPE = PROCEDURE [h: FSHandle, file: PATH, to: PATH, keep: CARDINAL, wantedUniqueID: UniqueID, remoteCheck: BOOL ¬ TRUE]
RETURNS [toFName: PATH];
GetInfoProc: TYPE = PROCEDURE [h: FSHandle, file: OpenFile]
RETURNS [fullFName, attachedTo: PATH, uniqueID: UniqueID, bytes: INT, mutability: PFS.Mutability, fileType: PFS.FileType];
SweepProc: TYPE ~ PROC [h: FSHandle, seconds: CARD];
Called a few (~10) times a minute by this package for miscellaneous housekeeping. The seconds argument specifies how long it's been since the last call.
ValidateProc: TYPE ~ PROC [h: FSHandle] RETURNS [obsolete: BOOL, downMsg: ROPE];
Called to validate a handle that might be stale.
If obsolete=TRUE, the handle is out of date and should be replaced (by calling appropriate getFSProc).
IF downMsg#NIL, the file system is known to exist but is down.
PFSNameToUnixNameProc: TYPE ~ PROCEDURE [h: FSHandle, file: PATH] RETURNS [ROPE];
For views that use the unix file system, returns the unix name corresponding to the named file. The implementor should try to avoid file system access; however, to implement the translation of file!H file system access will, of course, be needed.
CaseSensitiveProc: TYPE ~ PROCEDURE [h: FSHandle, file: PATH] RETURNS [BOOL];
Returns TRUE iff the case of any character in the file name is significant.
Registration
Register: PROC [flavor: ATOM, getHandle: GetHandleProc];
Register an(other) file ops implementation. Any existing registration for "flavor" disappears. "getHandle" may be NIL, to clear a registration.
GetHandleProc: TYPE ~ PROC [fs: ROPE, flavorSpecified: BOOL]
RETURNS [h: FSHandle, downMsg: ROPE];
Tries to find a file system of the given name.
If successful, creates FSHandle h and return [h, NIL].
If no file system responds and no server is known to exist, returns [NIL, NIL].
If fs is known to exist but is not responding, returns [NIL, message].
The flavorSpecified argument may be used by "layered" flavor implementations; if TRUE, the fs name originally presented to RemoteFile.GetServer[] had a flavor suffix.
Does not raise Error!
The client may Process.Abort a GetHandleProc.
Lookup
GetFS: PROC [fs: ROPE] RETURNS [h: FSHandle];
Tries to find a file system of the given name, using the cache.
! Error[$fsNotKnown, ...]
! Error[$fsNotAvailable, ...]
! Error[$viewNotImplemented, ...]
Controlling the cache.
If this is necessary the network environment is probably screwed up.
ClearCachedServer: PROC [fs: ROPE];
Error
Error: ERROR [code: ATOM, msg: ROPE];
Codes
$fsNotKnown : can't look up the server name.
$fsNotAvailable : can't contact it.
$viewNotImplemented : requested view not implemented by file system.
$software : "can't happen"
}...