Stream Poke

Stream.poke_begin()

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.

As an example of using the poke capabilities to write a sequence of data types as a single atomic unit using non-blocking I/O:

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", True, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_int(state, 5)
>>>      if result > 0:
>>>         result = stream.poke_double(state, 3.14)
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

In this 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 an exception is raised with error code -ErrorCode.WOULD_BLOCK. In this case, poke_end would not advance the output stream and the poked data would be 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.

However, if the poke_int_array and poke_double_array succeed then when poke_end advances the stream pointer. 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, 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 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 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.

Returns

result (int) – Returns 0 on success or -ErrorCode.WOULD_BLOCK if it cannot flush earlier data in the stream send buffer to make space.
state (t_stream_poke_state) – The initialized poke state.

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

Suppose the following binary structure is being sent:

struct {
    t_int8 temperature;
    t_uint8 status;
    t_int16 gyro_rates[3];
}

The code to send this structure as one atomic unit, while accounting for potential byte swapping due to byte order differences between server and client would be:

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> temperature = 25
>>> status = 1
>>> gyro_rates = array("h", [7 30 2])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", True, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, temperature)
>>>      if result > 0:
>>>         result = stream.poke_byte(state, status)
>>>      if result > 0:
>>>         result = stream.poke_short_array(state, gyro_rates, len(gyro_rates))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_end(state, status)

Finishes a “poke” operation by updating the stream buffer pointer so that all poked date is now marked as written to the streamm. It must be called after a sequence of poke_xxxx operations to complete the poke. If this function is not called before another poke_begin then the poked data is discarded from the stream buffer.

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

Parameters: state (t_stream_poke_state) – The “poke state” indicating how much data to add to the input stream.
Returns: result – If the stream is shutdown or closed, an exception is raised. Otherwise it returns 1 to indicate that the data was successfully written.
Return type: int
Raises: StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [0 0 0])
>>> short_buf = array("h", [0 0 0])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_short_array(state, short_buf, len(short_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_byte(state, data)

Writes a byte to the stream buffer. It attempts to store the byte in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then it raises an exception.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the byte is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 if the data is poked successfully. If the byte could not be poked without blocking, then it returns ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
data (char) – The value to be poked.

Returns

result – The number of bytes sent, which will always be 1. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_val = 123
>>> short_buf = array("h", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, byte_val)
>>>      if result > 0:
>>>         result = stream.poke_short_array(state, short_buf, len(short_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_byte_array(state, elements, num_elements)

writes an array of bytes to the stream buffer. It attempts to store the bytes in the stream buffer. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then an exception is raised.

The size of the stream send buffer must be at least as large as num_elements bytes.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the entire array is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 on success. If the entire array could not be poked without blocking, then it returns with the error code -ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
elements (array_like) – A buffer of at least num_elements bytes in which the received data will be stored.
num_elements (int) – The number of bytes from the elements array to poke.

Returns

result – The number of bytes sent. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [3 2 1])
>>> short_buf = array("h", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_short_array(state, short_buf, len(short_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_short(state, data)

Writes a short 16-bit integer to the stream buffer. It attempts to store the short integer in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then it returns a negative error code.

If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within the short integer when they are poked.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the short integer is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 if the data is poked successfully. If the short integer could not be poked without blocking, then -ErrorCode.WOULD_BLOCK is returned. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
data (short) – The value to be poked.

Returns

result – The number of 16-bit integers sent, which will always be 1. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_val = 123
>>> short_val = 32000
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, byte_val)
>>>      if result > 0:
>>>         result = stream.poke_short(state, short_val)
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_short_array(state, elements, num_elements)

writes an array of short 16-bit integers to the stream buffer. It attempts to store the short integers in the stream buffer. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then an exception is raised.

The size of the stream send buffer must be at least as large as num_elements 16-bit integers.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the entire array is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 on success. If the entire array could not be poked without blocking, then it returns with the error code -ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
elements (array_like) – A buffer of at least num_elements 16-bit integers in which the received data will be stored.
num_elements (int) – The number of 16-bit integers from the elements array to poke.

Returns

result – The number of 16-bit integers sent. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [3 2 1])
>>> short_buf = array("h", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_short_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_short_array(state, short_buf, len(short_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_int(state, data)

Writes a 32-bit integer to the stream buffer. It attempts to store the integer in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then it returns a negative error code.

If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within the integer when they are poked.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the integer is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 if the data is poked successfully. If the integer could not be poked without blocking, then -ErrorCode.WOULD_BLOCK is returned. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
data (int) – The value to be poked.

Returns

result – The number of 32-bit integers sent, which will always be 1. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_val = 123
>>> int_val = 32000
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, byte_val)
>>>      if result > 0:
>>>         result = stream.poke_int(state, int_val)
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_int_array(state, elements, num_elements)

writes an array of 32-bit integers to the stream buffer. It attempts to store the integers in the stream buffer. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then an exception is raised.

The size of the stream send buffer must be at least as large as num_elements 32-bit integers.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the entire array is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 on success. If the entire array could not be poked without blocking, then it returns with the error code -ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
elements (array_like) – A buffer of at least num_elements 32-bit integers in which the received data will be stored.
num_elements (int) – The number of 32-bit integers from the elements array to poke.

Returns

result – The number of 32-bit integers sent. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [3 2 1])
>>> int_buf = array("l", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_int_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_int_array(state, int_buf, len(int_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_long(state, data)

Writes a long 64-bit integer to the stream buffer. It attempts to store the long integer in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then it returns a negative error code.

If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within the long integer when they are poked.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the long integer is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 if the data is poked successfully. If the long integer could not be poked without blocking, then -ErrorCode.WOULD_BLOCK is returned. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
data (long) – The value to be poked.

Returns

result – The number of 64-bit integers sent, which will always be 1. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_val = 123
>>> long_val = 32000
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, byte_val)
>>>      if result > 0:
>>>         result = stream.poke_long(state, long_val)
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_long_array(state, elements, num_elements)

writes an array of long 64-bit integers to the stream buffer. It attempts to store the long integers in the stream buffer. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then an exception is raised.

The size of the stream send buffer must be at least as large as num_elements 64-bit integers.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the entire array is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 on success. If the entire array could not be poked without blocking, then it returns with the error code -ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
elements (array_like) – A buffer of at least num_elements 64-bit integers in which the received data will be stored.
num_elements (int) – The number of 64-bit integers from the elements array to poke.

Returns

result – The number of 64-bit integers sent. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [3 2 1])
>>> long_buf = array("q", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_long_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_long_array(state, long_buf, len(long_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_single(state, data)

Writes a single-precision 32-bit float to the stream buffer. It attempts to store the single-precision float in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then it returns a negative error code.

If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within the single-precision float when they are poked.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the single-precision float is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 if the data is poked successfully. If the single-precision float could not be poked without blocking, then -ErrorCode.WOULD_BLOCK is returned. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
data (float) – The value to be poked.

Returns

result – The number of 32-bit single-precision floats sent, which will always be 1. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_val = 123
>>> single_val = 3.14
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, byte_val)
>>>      if result > 0:
>>>         result = stream.poke_single(state, single_val)
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_single_array(state, elements, num_elements)

writes an array of single-precision 32-bit floats to the stream buffer. It attempts to store the single-precision floats in the stream buffer. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then an exception is raised.

The size of the stream send buffer must be at least as large as num_elements 32-bit single-precision floats.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the entire array is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 on success. If the entire array could not be poked without blocking, then it returns with the error code -ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
elements (array_like) – A buffer of at least num_elements 32-bit single-precision floats in which the received data will be stored.
num_elements (int) – The number of 32-bit single-precision floats from the elements array to poke.

Returns

result – The number of 32-bit single-precision floats sent. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [3 2 1])
>>> single_buf = array("f", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_single_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_single_array(state, single_buf, len(single_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_double(state, data)

Writes a double-precision 64-bit float to the stream buffer. It attempts to store the double-precision float in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then it returns a negative error code.

If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within the double-precision float when they are poked.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the double-precision float is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 if the data is poked successfully. If the double-precision float could not be poked without blocking, then -ErrorCode.WOULD_BLOCK is returned. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
data (float) – The value to be poked.

Returns

result – The number of 64-bit double-precision floats sent, which will always be 1. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_val = 123
>>> double_val = 3.14
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_byte(state, byte_val)
>>>      if result > 0:
>>>         result = stream.poke_double(state, double_val)
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.poke_double_array(state, elements, num_elements)

writes an array of double-precision 64-bit floats to the stream buffer. It attempts to store the double-precision floats in the stream buffer. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if poke_end is called. If an error occurs, then an exception is raised.

The size of the stream send buffer must be at least as large as num_elements 64-bit double-precision floats.

If listen or connect was called with the non-blocking flag set to False (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the entire array is poked into the buffer then 1 is returned. If an error occurs then an exception is raised and the stream should be closed.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. It returns 1 on success. If the entire array could not be poked without blocking, then it returns with the error code -ErrorCode.WOULD_BLOCK. If an error occurs then an exception is raised and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Parameters

state (t_stream_poke_state) – The poke state.
elements (array_like) – A buffer of at least num_elements 64-bit double-precision floats in which the received data will be stored.
num_elements (int) – The number of 64-bit double-precision floats from the elements array to poke.

Returns

result – The number of 64-bit double-precision floats sent. If the method would block then ErrorCode.WOULD_BLOCK is returned if the stream is non-blocking. If an error occurs, then an exception is raised.

Return type

int

Raises

StreamError – On a negative return code. A suitable error message may be retrieved using get_error_message.

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> byte_buf = array("b", [3 2 1])
>>> double_buf = array("d", [4 5 6])
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   while stream.poll(None, PollFlag.RECEIVE) > 0:
>>>      result, state = stream.poke_begin()
>>>      if result >= 0:
>>>         result = stream.poke_double_array(state, byte_buf, len(byte_buf))
>>>      if result > 0:
>>>         result = stream.poke_double_array(state, double_buf, len(double_buf))
>>>      result = stream.poke_end(state, result)
>>>      if result > 0:
>>>         result = stream.flush()
>>>      if result >= 0:
>>>         break
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()