Using Streams: 1.1 Using Streams: The Basics: Initializing a Stream

A stream is essentially a first-in-first-out data buffer, in which the writer is different from the reader. When the writer writes data to the stream, the kernel stores it in the buffer; when the reader requests information from the stream, the kernel retrieves the oldest data not yet read. The data is stored in a memory block; this block may be either fixed or movable. If it is movable, both the reader and the writer must lock the block before calling any stream routines.

Note that the kernel does not enforce who is the reader or writer to a stream. Any geode may call the appropriate stream library routine, passing in the token for a stream, and read or write data. However, in practice, only those threads with a legitimate interest in a stream will know the stream's token.

The serial and parallel drivers are built on top of the stream driver. There are separate routines to access the serial and parallel ports; these routines are discussed in Using the Serial Ports for the serial driver and Using the Parallel Ports for the parallel driver.

Creating a Stream

StreamOpen()

To create and initialize a new stream, call the routine StreamOpen() . This routine takes five arguments:

The handle of the stream driver.
The size of the stream buffer, in bytes. This may not be larger than 32767.
The GeodeHandle of the geode that will own this stream. When this geode exits, the stream will be freed; however, you should call StreamClose() before this happens.
A set of HeapFlags . The routine will have to allocate a block to hold the stream. The HeapFlags specify whether that block will be fixed or movable. If it is fixed, this argument should contain the flag HF_FIXED; otherwise it should be blank.
The pointer to a StreamToken variable. StreamOpen() will create the stream and write its token to this variable. You will need this token whenever you access the stream, for reading or writing.

If the creation is successful, StreamOpen() will return zero and store the stream's token in the StreamToken variable. You must see to it that both the reader and the writer have this token. If the stream cannot be created, the strategy routine will set an error flag and return either STREAM_CANNOT_ALLOC (if the memory for the stream's buffer cannot be allocated) or STREAM_BUFFER_TOO_LARGE (if the requested stream size was greater than 32767).

Assigning Readers and Writers

Once a stream is created, you must make sure that both ends will be managed--a stream that has only a writer or only a reader is not a useful stream.

When communicating with a device such as a serial or parallel port, the port is considered to be the entity on the other end. However, if two threads are communicating via a stream, you must make sure the other thread can gain access to the stream. The best way to do this is to set up a message that will be sent by the creator to the other geode. This message should contain as an argument the token of the stream and probably the direction of the stream (whether the creator will be reading or writing).

Once both geodes have the stream's token, each can access the stream normally. The next several sections explain how to access a stream for writing and reading.

GEOS SDK TechDocs |

1 Using Streams: The Basics | Next:

1.2 Blocking on Read or Write