plumbmsg - plumbing message module

include	"plumbmsg.m";
	plumbmsg: Plumbmsg;
	Msg: import plumbmsg;
plumbmsg = load Plumbmsg Plumbmsg->PATH;

Msg: adt
{
	src:		string;
	dst:		string;	
	dir:		string;
	kind:		string;
	attr:		string;
	data:		array of byte;
	# used by applications
	send: 	fn(msg: self ref Msg): int;
	recv: 	fn(): ref Msg;
	# used by plumb and send, recv
	pack: 	fn(msg: self ref Msg): array of byte;
	unpack: 	fn(b: array of byte): ref Msg;
};
Attr: adt
{
	name: string;
	val:  string;
};
init:	fn(doinput: int, rcvport: string, maxdata: int): int;
shutdown:	fn();
string2attrs:	fn(s: string): list of ref Attr;
attrs2string:	fn(l: list of ref Attr): string;
lookup:	fn(attrs: list of ref Attr, name: string): (int, 
string);

Description

The Plumbmsg module enables message-passing between applications.

Msg - message adt

The Msg adt encapsulates the message data sent between applications and the functions used to send and receive the messages. The components of the Msg adt are described below.

message format

Plumbing messages have a fixed format:

source\n
destination\n
directory\n
kind\n
attributes\n
nbytes\n
n bytes


source	The name of the program generating the message.
destination	The outport port from plumb that should deliver the message. In practice, destination is often left empty, and port will be determined by the particular implementation of plumbing.
directory	The directory in which to interpret the data (e.g., if the data is a local file name).
kind	The format of the data. (Currently, "text" is the only type that applications understand, but plumb will route any kind of data.)
attributes	A line of name=value pairs (e.g., click=7)
nbytes	The number of bytes of data.
n bytes	The data itself.

Msg.send

send: fn(msg: self ref Msg): int;

## returns number of bytes written.

Msg.send writes a plumbing message to the input file /chan/plumb.input.

Msg.send returns the number of bytes written (same as Sys->write, which does the writing).

Msg.recv

recv: fn(): ref Msg;

The Msg.recv function reads a plumbing message from the plumbing port file /chan/plumb.<rcvport> created using plumbmsg->init(). It returns a reference to a Msg adt that contains the message data.

Msg.pack

pack: fn(msg: self ref Msg): array of byte;

Msg.pack prepares a plumbing message in string form for sending as an array of byte.

Msg.unpack

unpack: fn(b: array of byte): ref Msg;

Msg.unpack takes a raw plumbing message and returns the information as a reference to a Msg adt.

init

init: fn(doinput: int, rcvport: string, maxdata: int): int;

## returns negative on error.

The init function of the plumbmsg module sets up the plumbing connections. Specifically, if doinput is nonzero, /chan/plumb.input will be opened for writing. If rcvport is not nil, the file /chan/plumb.<rcvport> will be opened for reading. The parameter maxdata is used to specify the size of an array of byte when plumbing messages are received.

Note: The function plumbmsg->init does not create the files. In the case of brutus, which runs under window manager, the files are created when the window manager starts.

Example - plumbmsg->init

This program fragment establishes plumbing by opening the file /chan/plumb.input for writing and opening the file /chan/plumb.edit for reading.

plumbed := 0;
plumbmsg = load Plumbmsg Plumbmsg->PATH;
if(plumbmsg->init(1, "edit", 1000) >= 0){
	plumbed = 1;
}

shutdown

shutdown:	fn();

The shutdown function writes a message to /chan/plumb.input that shuts down plumbing for the current plumbing port.

string2attrs

string2attrs:	fn(s: string): list of ref Attr;

The string2attrs function accepts a tab-separated list of attribute pairs and returns a list of references to Attr adts.

attrs2string

attrs2string:	fn(l: list of ref Attr): string;

The attrs2string function converts a list of references to Attr adts into a string of the form name=value name=value . . . . The name=value pairs are separated by a single space.

lookup

lookup:	fn(attrs: list of ref Attr, name: string): 	(int, 
string);

## returns (0, nil) if name not found in attrs.

The lookup function searches attrs for name. If name is found, lookup returns (1, value), where value is the value associated with name in the list of attribute pairs. If name is not found, lookup returns (0, nil).

[Top] [Prev] [Next] [Bottom]

infernosupport@lucent.com