stream_poke_begin :: Quanser C Functions

navigation bar

stream_poke_begin

Prepares the t_stream_poke_state to begin poking data to the stream.

Description

This function prepares the t_stream_poke_state to begin poking data to the stream. "Poking" involves writing to the stream buffer without writing to the underlying communication channel or updating the buffer pointers. It is particularly useful for writing "atomic" data to the stream whose length is not known in advance, such as characters being converted to the underlying character format of the stream. The "poke state" is used to keep track of how much data has been poked into the stream so far.

The stream_poke_end function must be called to end the poke operation. Failure to do so may potentially cause deadlock the next time stream_poke_begin is called.

An example of using the poke capabilities to write a sequence of data types as a single atomic unit using non-blocking I/O is provided below.In the example, the code pokes an integer and a double into the output stream. The data is not transmitted over the underlying communication channel but is maintained in the stream buffer. If at any time the operation would block because there is not enough space in the stream buffer, then -QERR_WOULD_BLOCK is returned. In this case, stream_poke_end does not advance the output stream and the poked data is discarded and not sent to the output stream. Hence, the next time the code is called it may write the same data again without the peer receiving two copies. The stream_poke_end returns the same error, -QERR_WOULD_BLOCK, to make it easier to propagate the error code.

However, if the stream_poke_int and stream_poke_double succeed then when stream_poke_end is called the stream pointer is advanced. Hence, the data will be sent to the output stream the next time the stream is flushed and subsequent sends/pokes to the stream will send new data. In this case, stream_poke_end returns one.

Thus, the integer and double are sent as one atomic unit to the output stream, because if not enough space is available in the stream buffer, then nothing is written to the output stream. Only if both quantities are written successfully is the data actually sent to the output stream.

Note that the stream_poke_xxxx functions may send data to the underlying communication channel (that remained from previous send operations), but the data being poked is never sent until stream_poke_end is called to indicate that the poked data may be sent to the output stream.

This function assumes that the stream is valid. It does not block because it does not access the underlying communication channel.

Prototype

t_error
stream_poke_begin(t_stream stream, t_stream_poke_state * state);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_steram_poke_state * state

The "poke state" to initialize.

Return value

This function only returns an error if one of the parameters is invalid or the stream is shutdown or closed.

Error codes

This function does not return any error code.

Requirements

Include Files	Libraries
quanser_stream.h	quanser_communications.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_stream_poke_state state;

result = stream_poke_begin(stream, &state);
if (result == 0) {
    result = stream_poke_int(stream, &state, 5);
    if (result > 0) {
        result = stream_poke_double(stream, &state, 3.14);
    }

    result = stream_poke_end(stream, &state, result);
    if (result > 0) {
        flush_result = stream_flush(stream);
    }
}