file2chan - create file connected to Limbo channel

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 file semantics are used, the goal does not have to be the creation of a server to replicate the duties of existing file systems (for example, 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 Introduction to Limbo Modules in Chapter 7. 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, mount, unmount - change file name space 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 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 respond 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, fprint, sprint - print formatted output).

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 (for example, 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, fprint, sprint - print formatted output).

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 Introduction to Limbo Modules in Chapter 7 for details.

Caveat

The read and write system calls for the file will not return until the server sends its reply on the appropriate channel. Consequently, the process doing the read or write should not be the one serving, to avoid deadlock.

file2chan - create file connected to Limbo channel

Description

file2chan (dir, file, flags)

Reads

Writes

Closes

Fid's

Caveat

See Also Limbo System Module bind, mount, unmount - change file name space open, create - open/create a file for reading or writing read, write, stream - read, write, or stream file print, fprint, sprint - print formatted output Introduction to Limbo Modules in Chapter 7

See Also

Limbo System Module

bind, mount, unmount - change file name space

open, create - open/create a file for reading or writing

read, write, stream - read, write, or stream file

print, fprint, sprint - print formatted output

Introduction to Limbo Modules in Chapter 7