Stream Protocol

The stream protocol provides generic interface to sequential byte stream-type devices, network services and interprocess communication channels (pipes). Streams are continuous queues of bytes, without any out-of-band delimiters. Generally, reading from a stream would delay reader until the entire buffer is filled unless sender used "push" operation in which case reading will be completed with only as many bytes as were present in the stream's queue at the time of receiving the "push" message. Some devices (for example, serial lines) may appear as streams with senders pushing data after every byte.

Stream protocol includes the following requests (mem is the symbolic name for the memory protocol).

ST_READ([mem{MEM_WRITE}, ...])

This request reads bytes sequentially from stream into the memory objects provided as its in-arguments until one of the following conditions is met:

• all memory objects (buffers) are full;
• there's no more data queued and sender performed "push" operation;
• sender indicated that it will not send any more data (end of transmission condition).

The result code is the total number of bytes read; zero result code is usually returned only when end of transmission condition is present. Since result codes are positive values of 32-bit signed integers, the maximal number of bytes which can be read by a single ST_READ request is 2³¹-1.

As a special case, ST_READ without in-arguments can be used to discard all queued input data. The number of bytes discarded will be returned as result code.

Cancellation of ST_READ will cause it to return as soon as possible, with the actual number of data bytes read as the result code.

ST_WRITE([mem{MEM_READ}, ...])

This request writes bytes sequentially into stream from the memory objects (buffers) provided as its in-arguments and returns the actual number of bytes written as its return code. Return code with value less than the sum of lengths of buffers indicates some problem at receiving side. The maximal number of bytes which can be written by a single ST_WRITE request is 2³¹-1.

If a null object is specified as one of the arguments all preceding data in the stream will be "pushed", i.e. immediate delivery to the recipient will be initiated. This does not cause ST_WRITE to wait for the completion of the delivery.

As a special case, ST_WRITE without in-arguments can be used to wait for all queued output data to be delivered ("pushing" is implicitly performed before waiting in this case, so doing ST_WRITE with null object prior to ST_WRITE without arguments is redundant).

Cancellation of ST_WRITE will cause it to return as soon as possible, with the actual number of data bytes written as the result code.

ST_LOCK(locker_id) -> lock{*}

ST_LOCK creates a lock object associated with the stream. This object can be used to implement advisory locks allowing several processes to share the same stream. locker_id is an arbitrary object identifying the owner of the lock (see definition of LOCK_CHECK).

The returned access to lock object allows both shared and exclusive locks.

None of stream protocol requests are granted.