Oberon || Library || Module Index || Search Engine || Definition || Module


Ulm's Oberon Library:
SMStreams


NAME

SMStreams - bidirectional IPC using shared memory

SYNOPSIS

TYPE Stream = POINTER TO StreamRec;
TYPE StreamRec = RECORD (Streams.StreamRec) END;


CONST MRingError = 0; CONST SRingError = 1; CONST PartnerNotAliveError = 2; CONST WriteAfterCloseError = 3; CONST DeadlockError = 4; CONST NotAloneError = 5; CONST ConnectionNotReadyError = 6; CONST errorcodes = 7; TYPE ErrorCode = SHORTINT; TYPE ErrorEvent = POINTER TO ErrorEventRec; TYPE ErrorEventRec = RECORD (Events.EventRec) errorcode: ErrorCode; END; VAR error: Events.EventType; VAR errormsg: ARRAY errorcodes OF Events.Message;

PROCEDURE Open(VAR s: Streams.Stream; filename: ARRAY OF CHAR; bufmode: Streams.BufMode; errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE CreateOpenCondition(VAR condition: Conditions.Condition; filename: ARRAY OF CHAR); PROCEDURE TestAndOpen(VAR s: Streams.Stream; condition: Conditions.Condition; bufmode: Streams.BufMode; errors: RelatedEvents.Object) : BOOLEAN;

PROCEDURE Listen(VAR socket: Networks.Socket; filename: ARRAY OF CHAR; size: SysTypes.Size; errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE CreateSomeSocket(VAR socket: Networks.Socket; VAR address: ARRAY OF CHAR; size: SysTypes.Size; errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Release(socket: Networks.Socket);

PROCEDURE Accept(socket: Networks.Socket; VAR s: Streams.Stream; bufmode: Streams.BufMode) : BOOLEAN; PROCEDURE CreateAcceptCondition(s: Streams.Stream; VAR cond: Conditions.Condition);

PROCEDURE CreateAddress(VAR address: Networks.Address; filename: ARRAY OF CHAR; size: SysTypes.Size); PROCEDURE ConvertAddress(address: Networks.Address; VAR filename: ARRAY OF CHAR; VAR size: SysTypes.Size); PROCEDURE SetAddress(address: Networks.Address; filename: ARRAY OF CHAR; size: SysTypes.Size);

DESCRIPTION

SMStreams provides a Streams interface for bidirectional interprocess communication and supports Networks. It uses SysMemory.Map to create a shared memory region in which the communication takes place, and uses the signals SysSignals.USR1 and SysSignals.USR2 for synchronization. Thus, the communicating processes must both run on the same machine and have the same effective user-id.

SMStreams supports the waiting condition interface provided by StreamConditions.

Open tries to create a stream that maps the file filename which must have been created by some other process by calling Listen or CreateSomeSocket. The stream has a memory area of the size which was given to Listen. Alternatively, CreateOpenCondition and TestAndOpen may be used like the equally named procedures of Networks.

Listen creates a file to be mapped into memory and a socket which may be used later to wait for incoming connections. CreateSomeSocket works like Listen but takes an unique file name which has been returned by UnixTmpNames.

Accept waits for incoming connections for socket socket. The socket must have been created and prepared by Listen. When Accept returns, the stream s is connected with the new communication partner.

The buffering mode bufmode can be chosen from the modes supplied by Streams. Please notice that the choice of the right buffering mode is vital to good performance. Usually, Streams.nobuf is fastest, but not in every case, e.g. unbuffered bytewise I/O will result in massive synchronization of the two processes. On the other hand buffered operation on large structures will double the amount of data moved around in memory. Be free to choose different buffering modes for each side of the communication.

AcceptCondition creates a condition which evaluates to TRUE if a subsequent Accept would not block for stream s.

Release frees the resources used by the socket socket.

SMStreams supports the interface of Networks: CreateAddress takes a filename and a memory size and converts it into a newly created network address. ConvertAddress returns the address data for an SMStreams which consists of a filename and a memory size. SetAddress allows to change an existing network address.

DIAGNOSTICS

All procedures return FALSE in case of errors and relate their error events to errors .

Accept relates its errors to stream s. By default, these events are being queued.

Errorcodes:

MRingError
The first communication area could not be created. Check if size is >0.
SRingError
The second communication area could not be created. Check if size is >0.
PartnerNotAliveError
An operation did not reach the other side because it has ceased to exist.
WriteAfterCloseError
The other side has already closed the stream when a write operation was attempted.
DeadlockError
A deadlock situation occurred.
NotAloneError
Some other process has already mapped the connection file with the same opening procedure.
ConnectionNotReadyError
Open or TestAndOpen could not establish the connection.

SEE ALSO

Conditions
interface for conditions
Networks
general abstraction for bidirectional connections
RelatedEvents
handling of error events
SysMemory
interface for the mmap(2) system call
Streams
stream operations
StreamConditions
stream I/O waiting conditions

AUTHOR

Till Franke, University of Ulm
some minor revisions are due to Andreas Borchert, University of Ulm
Edited by: borchert, last change: 2003/07/10, revision: 1.5, converted to HTML: 2003/07/10

Oberon || Library || Module Index || Search Engine || Definition || Module