Using Streams: 1.2 Using Streams: The Basics: Blocking on Read or Write

StreamBlocker, StreamError, StreamGetError(), StreamSetError()

A stream is a data buffer of limited size. When a thread writes to the stream, there is a chance it could run out of space. Similarly, when a thread reads from the stream, there is a possibility that it will try to read more data than is available; for example, it might try to read 500 bytes, when only 250 bytes of data are sitting in the stream.

There are two ways you can deal with these situations. One way is, you can instruct the thread to block. For example, if you try to write 500 bytes to a stream and there is only 200 bytes of space available, the driver will write the first 200 bytes to that space, then have the writing thread block until more space is available (i.e. until the reading thread has read some data). The writing thread will not resume execution until all the data has been written. Similarly, a reading thread could block until the stream provided all the data it requested.

The other approach is to have the stream driver write or read all it can, then return an appropriate error code. This requires a little more work by the calling thread, as it cannot assume that all the data is always read or written; however, it avoids the risk of deadlock.

All read and write routines are passed a member of the StreamBlocker enumerated type. This type has two members: STREAM_BLOCK, indicating that the calling thread should block in the situations described above; and STREAM_NO_BLOCK, indicating that the routine should immediately return with an error if enough space is not available. A single thread may, if it wishes, pass STREAM_BLOCK sometimes and STREAM_NO_BLOCK sometimes.

If a stream routine returns an error, the error will be a member of the StreamError enumerated type. The possible error values are described in the section for each routine.

Sometimes the device or application at the other end of the stream will need to return a special error value. For example, it may have its own error enumerated type, and may wish to signal an error to the application on the other end of the stream. It can do this by calling StreamSetError() . This routine is passed four arguments:

The GeodeHandle of the stream driver.
The StreamToken of the stream.
A member of the StreamRoles enumerated type. The only appropriate values here are STREAM_ROLES_WRITER or STREAM_ROLES_READER.
A word-sized error code.

If the routine is succesful, it returns zero. Otherwise, it returns a member of the StreamError enumerated type.

To read a an error value set by the other side of a stream, call StreamGetError() . This routine is passed four arguments:

The GeodeHandle of the stream driver.
The StreamToken of the stream.
A member of the StreamRoles enumerated type. The only appropriate values here are STREAM_ROLES_WRITER or STREAM_ROLES_READER.
A pointer to a word-sized variable.

If successful, the routine returns zero, and writes the other side's error value to the passed word-sized argument. If it is unsuccessful, the routine returns a StreamError value.

GEOS SDK TechDocs |

1.1 Initializing a Stream | Next:

1.3 Writing Data to a Stream