file2chan

file2chan - create file connected to Limbo channel

Synopsis

include "sys.m";
sys:= load Sys Sys->PATH;
Rread: type chan of (array of byte, string);
Rwrite: type chan of (int,      string);
FileIO: adt
{
    read:  chan of (int, int,      int, Rread);
    write: chan of (int, array of byte, int, Rwrite);
};
file2chan: fn(dir, file: string, flags: int): ref FileIO;

Description

The file2chan function provides an interface for creating a Limbo channel and an associated entry (file) in the file name space. A client communicates with the server using open, read and write. The system transforms the client's file operations into tuples that are delivered to the server on the channel associated with file. When the server responds, the client's file operations complete.

Although the interface is couched in file semantics, the goal need not be the creation a server to replicate the duties of existing file systems (e.g., persistent storage of data). The server can be designed to provide new services.

file2chan (dir, file, flags)

The file2chan function returns a FileIO type holding two channels used by the system to deliver Tread and Twrite Styx messages to the server. See Limbo Modules. The arguments are:


dir	The existing directory where the file is to be created.
file	The file created by file2chan. It is held in a directory, containing just that one file, unioned in dir.
flags	The flags argument specifies how that union is created; see bind for a description of the flags.

Reads

When the client invokes the read system call on the file, the server receives a tuple, (offset, count, fid, rc), on the read channel of returned ref FileIO. The server should interpret that as a request as follows:


offset	The offset from the beginning of the file.
count	The size of the data request.
fid	An unique identifier for managing multiplexed requests on file.
rc	The channel for delivery of the requested data.

To allow the client to complete its read request successfully, the server should respond by sending into rc a tuple, (data, nil), where data satisfies the client's request.

To create an unsuccessful read request for the client, the server should response on rc with a tuple, (nil, errmsg), where errmsg is a string describing the error condition. The errmsg string becomes the system error for the client (See print).

The client blocks in its read system call until the server sends its reply.

Writes

When the client does a write system call on the file, the server receives a tuple, (offset, data, fid, wc), on the write channel of the returned ref FileIO. That request should be interpreted as follows:


offset	The offset from the beginning of the file where the data should be written.
data	The data to be written into the file.
fid	An unique identifier for managing multiplexed requests on file.
wc	A channel for delivery of a write-response message.

The server should respond with a tuple (count, string) on wc, the channel received in the tuple from the write channel. To indicate a successful write operation to the client the server's response should be (count, nil), where count is the number of bytes (i.e., len data) received from the client.

To make the client's write request fail, the server's response should be (0, errmsg), where errmsg describes the problem. The errmsg string becomes the system error for the client (See print).

The client blocks in its write system call until the server sends its reply.

Closes

When file is closed for reading (writing), the server will receive a read (write) message with a nil rc (wc). The server can use these events to determine when to stop processing for a given fid.

Fid's

The fid received by the server can be used to manage the multiplexing of multiple active clients sharing a single file. See Limbo Modules for details.

Caveat

The read and write system calls for the file will not return until the server sends it reply on the appropriate channel; consequently, the process doing the read or write should not be the one serving, lest it deadlock.

infernosupport@lucent.com