Stream Receive

Stream.receive(buffer, buffer_size)

Receives data over a client stream. It attempts to receive buffer_size bytes from the communication channel.

If listen or connect was called with the non-blocking flag set to False, then this function blocks until all the data is read. If the connection has been closed gracefully, then it returns 0 only once there is no more data to receive. Otherwise it returns the number of bytes read before the connection closed. Once all the data in the stream buffer is exhausted, it will return 0 to indicate the connection has been closed. If an error occurs, then it raises an exception.

If listen or connect was called with the non-blocking flag set to True, then this function does not block. If no data is available at all, then it returns -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with PollFlag.RECEIVE to determine when data becomes available; otherwise, it returns the number of bytes received.

Unlike the receive_byte_array function, this function does not require that the stream receive buffer be at least buffer_size bytes in length. Hence, it allows smaller stream buffers to be used.

This function does not support two threads calling receive at the same time; however, send or flush may be called by another thread at the same time as receive.

The semantics of this function differ from the BSD recv() socket function because it receives buffer_size bytes in blocking mode rather than the number of bytes that were sent in a single send() call at the peer. The semantics differ because this function attempts to “read ahead” by keeping the stream buffer full, thereby minimizing the number of receive operations performed on the internal connection. Also, due to buffering of the send operation, the number of send() calls made at the peer may not correspond to the number expected.

Parameters

buffer (array_like) – A buffer of at least buffer_size bytes in which the received data will be stored.
buffer_size (int) – The number of bytes available in the buffer.

Returns

The number of bytes received, which may be less than buffer_size bytes for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough bytes are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = bytearray(buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_bytes(elements, num_elements)

Receives an array of bytes over a client stream. It has the same semantics as the receive function.

Unlike the receive_byte_array function, this function does not require that the stream receive buffer be at least num_elements bytes in length. Hence, it allows smaller stream buffers to be used.

Parameters

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 available in the buffer.

Returns

The number of bytes received, which may be less than num_elements bytes for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough bytes are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = bytearray(buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive_bytes(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_byte_array(elements, num_elements)

Receives an array of bytes over a client stream. It differs from the receive_bytes function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of bytes.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer bytes are available then the size of the entire array then it returns with the error code -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer bytes left to receive than the size of the entire array then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it raises an exception.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough bytes are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = bytearray(buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   result = stream.receive_byte_array(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_shorts(elements, num_elements)

Receives an array of 16-bit integers over a client stream. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each short integer that it receives before storing them in the given buffer.

Unlike the receive_short_array function, this function does not require that the stream receive buffer be at least num_elements 16-bit integers in length. Hence, it allows smaller stream buffers to be used.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer bytes are available then the size of a short integer then it returns -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns the number of short integers received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a short integer. Otherwise it returns the number of short integers read before the connection closed. Once there are fewer bytes left to receive than the size of a short integer then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

The number of 16-bit integers received, which may be less than num_elements integers for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 16-bit inegers are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("h", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive_shorts(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_short_array(elements, num_elements)

Receives an array of 16-bit integers over a client stream. It differs from the receive_shorts function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of 16-bit integers. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each short integer that it receives before storing them in the given buffer.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer 16-bit integers are available then the size of the entire array then it returns with the error code -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer 16-bit integers left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer 16-bit integers left to receive than the size of the entire array then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it raises an exception.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 16-bit integers are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("h", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   result = stream.receive_short_array(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_ints(elements, num_elements)

Receives an array of 32-bit integers over a client stream. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each integer that it receives before storing them in the given buffer.

Unlike the receive_int_array function, this function does not require that the stream receive buffer be at least num_elements 32-bit integers in length. Hence, it allows smaller stream buffers to be used.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer bytes are available then the size of a integer then it returns -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns the number of integers received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a integer. Otherwise it returns the number of integers read before the connection closed. Once there are fewer bytes left to receive than the size of a integer then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

The number of 32-bit integers received, which may be less than num_elements integers for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 32-bit inegers are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("l", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive_ints(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_int_array(elements, num_elements)

Receives an array of 32-bit integers over a client stream. It differs from the receive_ints function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of 32-bit integers. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each integer that it receives before storing them in the given buffer.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer 32-bit integers are available then the size of the entire array then it returns with the error code -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer 32-bit integers left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer 32-bit integers left to receive than the size of the entire array then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it raises an exception.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 32-bit integers are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("l", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   result = stream.receive_int_array(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_longs(elements, num_elements)

Receives an array of 64-bit integers over a client stream. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each long integer that it receives before storing them in the given buffer.

Unlike the receive_long_array function, this function does not require that the stream receive buffer be at least num_elements 64-bit integers in length. Hence, it allows smaller stream buffers to be used.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer bytes are available then the size of a long integer then it returns -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns the number of long integers received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a long integer. Otherwise it returns the number of long integers read before the connection closed. Once there are fewer bytes left to receive than the size of a long integer then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

The number of 64-bit integers received, which may be less than num_elements integers for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 64-bit inegers are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("q", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive_longs(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_long_array(elements, num_elements)

Receives an array of 64-bit integers over a client stream. It differs from the receive_longs function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of 64-bit integers. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each long integer that it receives before storing them in the given buffer.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer 64-bit integers are available then the size of the entire array then it returns with the error code -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer 64-bit integers left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer 64-bit integers left to receive than the size of the entire array then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it raises an exception.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 64-bit integers are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("q", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   result = stream.receive_long_array(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_singles(elements, num_elements)

Receives an array of 32-bit single-precision floats over a client stream. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each single-precision float that it receives before storing them in the given buffer.

Unlike the receive_single_array function, this function does not require that the stream receive buffer be at least num_elements 32-bit single-precision floats in length. Hence, it allows smaller stream buffers to be used.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer bytes are available then the size of a single 32-bit single-precision float then it returns -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns the number of 32-bit single-precision floats received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a 32-bit single-precision float. Otherwise it returns the number of 32-bit single-precision floats read before the connection closed. Once there are fewer bytes left to receive than the size of a 32-bit single-precision float then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

The number of 32-bit single-precision floats received, which may be less than num_elements floats for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 32-bit single-precision floats are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("f", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive_singles(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_single_array(elements, num_elements)

Receives an array of 32-bit single-precision floats over a client stream. It differs from the receive_singles function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of 32-bit single-precision floats. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each 32-bit single-precision float that it receives before storing them in the given buffer.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer 32-bit single-precision floats are available then the size of the entire array then it returns with the error code -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer 32-bit single-precision floats left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer 32-bit single-precision floats left to receive than the size of the entire array then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it raises an exception.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 32-bit single-precision floats are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("f", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   result = stream.receive_single_array(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_doubles(elements, num_elements)

Receives an array of 64-bit double-precision floats over a client stream. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each double-precision float that it receives before storing them in the given buffer.

Unlike the receive_double_array function, this function does not require that the stream receive buffer be at least num_elements 64-bit double-precision floats in length. Hence, it allows smaller stream buffers to be used.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer bytes are available then the size of a double 64-bit double-precision float then it returns -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns the number of 64-bit double-precision floats received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes left to receive than the size of a 64-bit double-precision float. Otherwise it returns the number of 64-bit double-precision floats read before the connection closed. Once there are fewer bytes left to receive than the size of a 64-bit double-precision float then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it returns a negative error code.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

The number of 64-bit double-precision floats received, which may be less than num_elements floats for non-blocking streams. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 64-bit double-precision floats are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("d", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   bytes_read = stream.receive_doubles(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.receive_double_array(elements, num_elements)

Receives an array of 64-bit double-precision floats over a client stream. It differs from the receive_doubles function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. It also requires that the stream receive buffer be at least as large as the array of 64-bit double-precision floats. If the stream has been configured to swap bytes using set_swap_bytes then this function will swap the order of the bytes within each 64-bit double-precision float that it receives before storing them in the given buffer.

If listen or connect was called with the non-blocking flag set to False (0), then this function blocks until all the data is read.

If listen or connect was called with the non-blocking flag set to True (1), then this function does not block. If fewer 64-bit double-precision floats are available then the size of the entire array then it returns with the error code -ErrorCode.WOULD_BLOCK. In this case, the poll function may be used with the PollFlag.RECEIVE flag to determine when data becomes available. Otherwise it returns 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer 64-bit double-precision floats left to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer 64-bit double-precision floats left to receive than the size of the entire array then it will return 0 to indicate the connection has been closed. Use receive to receive any remaining bytes if required. If an error occurs, then it raises an exception.

This function does not support two threads receiving data at the same time. However, data may be sent 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

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 available in the buffer.

Returns

Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If not enough 64-bit double-precision floats are available and the method would block, then -ErrorCode.WOULD_BLOCK is returned for non-blocking streams. If an error occurs, then an exception is raised.

Return type

int

Raises

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

Example

>>> from quanser.communications import Stream
>>> buffer_size = 64
>>> buffer = array("d", [0] * buffer_size)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, buffer_size, buffer_size)
>>> try:
>>>   result = stream.receive_double_array(buffer, buffer_size)
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()