Stream Send

Stream.flush()

Flushes the stream buffer. It attempts to send the contents of the buffer over the communication channel. If an error occurs, then it raises an exception. If the connection is closed, it is considered an error condition.

If listen or connect was called with the non-blocking flag set to False, then this function blocks until all the data in the buffer is sent.

If listen or connect was called with the non-blocking flag set to True, then this function does not block. It attempts to send all the data remaining in the stream buffer. However, if this operation would block, then it returns -ErrorCode.WOULD_BLOCK, even if it has already sent some of the data. In this case, the poll function may be used with PollFlag.FLUSH to determine when at least one more bytes may be flushed.

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

Raises: StreamError – On non-zero return code. A suitable error message may be retrieved using get_error_message.
Returns: Returns 1 on success. If no more data is available and the connection has been closed gracefully, then 0 is returned. If 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

Example

Flush the send buffer in order to send a message that is smaller than the size of the buffer.

>>> from quanser.communications import Stream
>>> message = "Hello".encode()
>>> num_bytes = len(message)
>>> send_buffer_size = 64
>>> receive_buffer_size = 64
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, send_buffer_size, receive_buffer_size)
>>> try:
>>>   bytes_written = stream.send(message, num_bytes)
>>>   stream.flush()
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send(buffer, buffer_size)

Writes data to the stream buffer. It attempts to store buffer_size bytes 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then an exception is raised. If the connection is closed, it is considered an error condition.

If listen or connect was called with the non-blocking flag set to False, then this function may block attempting to flush the stream buffer. All the data will be consumed and the total number of bytes sent is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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, then this function does not block. It returns the number of bytes sent successfully, which will be between 1 and buffer_size (unless buffer_size is zero). If no bytes could be sent without blocking, then the function returns 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 calling send or flush 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 are comparable to the BSD send() socket function.

Parameters

buffer (array_like) – A buffer of at least buffer_size bytes containing the data to be sent.
buffer_size (int) – The number of bytes to send from the buffer.

Returns

The number of bytes sent, which may be less than buffer_size bytes for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if buffer_size is zero.

Return type

int

Raises

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

Examples

Send a text message immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> message = "Hello".encode()
>>> num_bytes = len(message)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   bytes_written = stream.send(message, num_bytes)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Send 2 doubles immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> data = bytearray(struct.pack("!dd", 1.2, 3.4))
>>> num_bytes = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   bytes_written = stream.send(data, num_bytes)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_byte(data)

Writes a single byte to the stream buffer. It is has the same semantics as the send function, except that it only sends a single byte.

The semantics of this function are comparable to the BSD send() socket function.

Parameters: data (char) – The byte to send.
Returns: The number of bytes sent, which will always be 1 unless no data was sent in non-blocking I/O. 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.

Examples

Send one byte immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   bytes_written = stream.send_byte(123)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_bytes(elements, num_elements)

This function writes an array of bytes to the stream buffer. It is has the same semantics as the send function.

Unlike the send_byte_array function, this function does not require that the stream send 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 containing the data to be sent.
num_elements (int) – The number of bytes to send from the buffer.

Returns

The number of bytes sent, which may be less than num_elements bytes for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if num_elements is zero.

Return type

int

Raises

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

Examples

Send a text message immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> message = "Hello".encode()
>>> num_bytes = len(message)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   bytes_written = stream.send_bytes(message, num_bytes)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Send 4 bytes immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("b", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_bytes(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_byte_array(elements, num_elements)

Writes an array of bytes to the stream buffer. It attempts to store the bytes in the stream buffer. It differs from the send_bytes function in that it treats the entire array as an atomic unit. 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it throws an exception. If the connection is closed it is considered an error condition.

Unlike the send_bytes function, the size of the stream send buffer must be at least as large as the number of bytes being sent.

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. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 array is sent successfully. If the array could not be sent without blocking, then it returns 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of bytes to send from the buffer.

Returns

Returns 1 on success. 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.

Examples

Send 4 bytes atomically by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("b", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   bytes_written = stream.send_byte_array(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_short(data)

Writes a 16-bit short 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. 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 it is sent.

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. All the data will be consumed and the total number of short integers sent is returned (1). Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 the number of short integers sent successfully, which will be 1. If the short integer could not be sent 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 sending or flushing 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: data (short) – The short to send.
Returns: The number of 16-bit integers sent, which will always be 1 unless no data was sent in non-blocking I/O. 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.

Examples

Send one 16-bit integer immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   shorts_written = stream.send_short(123)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_shorts(elements, num_elements)

This function writes an array of 16-bit short integers to the stream buffer. It attempts to store the short integers 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it returns a negative error code. Unlike the send_short_array function, this function does not require that the stream send buffer be at least num_elements 16-bit integers in length. Hence, it allows smaller stream buffers to be used.

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 when they are sent.

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. All the data will be consumed and the total number of short integers sent is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned 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 the number of short integers sent successfully, which will be between 1 and num_elements (unless num_elements is zero). If no short integers could be sent 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 16-bit integers to send from the buffer.

Returns

The number of 16-bit integers sent, which may be less than num_elements for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if num_elements is zero.

Return type

int

Raises

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

Examples

Send 4 16-bit integers immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("h", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_shorts(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_short_array(elements, num_elements)

Writes an array of 16-bit integers to the stream buffer. It attempts to store the integers in the stream buffer. It differs from the send_shorts function in that it treats the entire array as an atomic unit. 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it throws an exception.

Unlike the send_shorts function, the size of the stream send buffer must be at least as large as the number of bytes being sent.

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. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 array is sent successfully. If the array could not be sent without blocking, then it returns 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 16-bit integers to send from the buffer.

Returns

Returns 1 on success. 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.

Examples

Send 4 16-bit integers atomically by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("h", [1, 2, 3, 4])
>>> num_elements = len(elements)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_short_array(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_int(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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. 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 32-bit integer when it is sent.

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. All the data will be consumed and the total number of 32-bit integers sent is returned (1). Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 the number of 32-bit integers sent successfully, which will be 1. If the 32-bit integer could not be sent 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 sending or flushing 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: data (int) – The 32-bit integer to send.
Returns: The number of 32-bit integers sent, which will always be 1 unless no data was sent in non-blocking I/O. 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.

Examples

Send one 32-bit integer immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   ints_written = stream.send_int(123456)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_ints(elements, num_elements)

This function writes an array of 32-bit integers to the stream buffer. It attempts to store the integers 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it returns a negative error code. Unlike the send_int_array function, this function does not require that the stream send buffer be at least num_elements 32-bit integers in length. Hence, it allows smaller stream buffers to be used.

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 integer when they are sent.

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. All the data will be consumed and the total number of 32-bit integers sent is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned 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 the number of 32-bit integers sent successfully, which will be between 1 and num_elements (unless num_elements is zero). If no 32-bit integers could be sent 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 32-bit integers to send from the buffer.

Returns

The number of 32-bit integers sent, which may be less than num_elements for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if num_elements is zero.

Return type

int

Raises

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

Examples

Send 4 32-bit integers immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("l", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_ints(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_int_array(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 differs from the send_ints function in that it treats the entire array as an atomic unit. 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it throws an exception.

Unlike the send_ints function, the size of the stream send buffer must be at least as large as the number of bytes being sent.

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. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 array is sent successfully. If the array could not be sent without blocking, then it returns 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 32-bit integers to send from the buffer.

Returns

Returns 1 on success. 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.

Examples

Send 4 32-bit integers atomically by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("l", [1, 2, 3, 4])
>>> num_elements = len(elements)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_int_array(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_long(data)

Writes a 64-bit long 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. 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 it is sent.

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. All the data will be consumed and the total number of long integers sent is returned (1). Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 the number of long integers sent successfully, which will be 1. If the long integer could not be sent 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 sending or flushing 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: data (long) – The long to send.
Returns: The number of 64-bit integers sent, which will always be 1 unless no data was sent in non-blocking I/O. 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.

Examples

Send one 64-bit integer immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   longs_written = stream.send_long(123)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_longs(elements, num_elements)

This function writes an array of 64-bit long integers to the stream buffer. It attempts to store the long integers 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it returns a negative error code. Unlike the send_long_array function, this function does not require that the stream send buffer be at least num_elements 64-bit integers in length. Hence, it allows smaller stream buffers to be used.

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 when they are sent.

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. All the data will be consumed and the total number of long integers sent is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned 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 the number of long integers sent successfully, which will be between 1 and num_elements (unless num_elements is zero). If no long integers could be sent 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 64-bit integers to send from the buffer.

Returns

The number of 64-bit integers sent, which may be less than num_elements for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if num_elements is zero.

Return type

int

Raises

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

Examples

Send 4 64-bit integers immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("q", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_longs(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_long_array(elements, num_elements)

Writes an array of 64-bit integers to the stream buffer. It attempts to store the integers in the stream buffer. It differs from the send_longs function in that it treats the entire array as an atomic unit. 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it throws an exception.

Unlike the send_longs function, the size of the stream send buffer must be at least as large as the number of bytes being sent.

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. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 array is sent successfully. If the array could not be sent without blocking, then it returns 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 64-bit integers to send from the buffer.

Returns

Returns 1 on success. 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.

Examples

Send 4 64-bit integers atomically by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("q", [1, 2, 3, 4])
>>> num_elements = len(elements)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_long_array(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_single(data)

Writes a 32-bit single-precision 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. 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 it is sent.

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. All the data will be consumed and the total number of single-precision floats sent is returned (1). Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 the number of single-precision floats sent successfully, which will be 1. If the single-precision float could not be sent 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 sending or flushing 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: data (float) – The single-precision float to send.
Returns: The number of 32-bit single-precision floats sent, which will always be 1 unless no data was sent in non-blocking I/O. 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.

Examples

Send one 32-bit single-precision float immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   singles_written = stream.send_single(3.14)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_singles(elements, num_elements)

This function writes an array of 32-bit single-precision floats to the stream buffer. It attempts to store the single-precision floats 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it returns a negative error code. Unlike the send_single_array function, this function does not require that the stream send buffer be at least num_elements 32-bit single-precision floats in length. Hence, it allows smaller stream buffers to be used.

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 when they are sent.

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. All the data will be consumed and the total number of single-precision floats sent is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned 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 the number of single-precision floats sent successfully, which will be between 1 and num_elements (unless num_elements is zero). If no single-precision floats could be sent 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 32-bit single-precision floats to send from the buffer.

Returns

The number of 32-bit single-precision floats sent, which may be less than num_elements for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if num_elements is zero.

Return type

int

Raises

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

Examples

Send 4 32-bit single-precision floats immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("f", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_singles(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_single_array(elements, num_elements)

Writes an array of 32-bit single-precision floats to the stream buffer. It attempts to store the single-precision floats in the stream buffer. It differs from the send_singles function in that it treats the entire array as an atomic unit. 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it throws an exception.

Unlike the send_singles function, the size of the stream send buffer must be at least as large as the number of bytes being sent.

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. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 array is sent successfully. If the array could not be sent without blocking, then it returns 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 32-bit single-precision floats to send from the buffer.

Returns

Returns 1 on success. 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.

Examples

Send 4 32-bit single-precision floats atomically by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("f", [1, 2, 3, 4])
>>> num_elements = len(elements)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_single_array(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_double(data)

Writes a 64-bit double-precision 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. 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 it is sent.

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. All the data will be consumed and the total number of double-precision floats sent is returned (1). Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 the number of double-precision floats sent successfully, which will be 1. If the double-precision float could not be sent 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 sending or flushing 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: data (float) – The double-precision float to send.
Returns: The number of 64-bit double-precision floats sent, which will always be 1 unless no data was sent in non-blocking I/O. 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.

Examples

Send one 64-bit double-precision float immediately by writing it to the stream and then flushing the buffer.

>>> from quanser.communications import Stream
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   doubles_written = stream.send_double(3.14)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_doubles(elements, num_elements)

This function writes an array of 64-bit double-precision floats to the stream buffer. It attempts to store the double-precision floats 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it returns a negative error code. Unlike the send_double_array function, this function does not require that the stream send buffer be at least num_elements 64-bit double-precision floats in length. Hence, it allows smaller stream buffers to be used.

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 when they are sent.

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. All the data will be consumed and the total number of double-precision floats sent is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. If an error occurs then the error code is returned 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 the number of double-precision floats sent successfully, which will be between 1 and num_elements (unless num_elements is zero). If no double-precision floats could be sent 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 64-bit double-precision floats to send from the buffer.

Returns

The number of 64-bit double-precision floats sent, which may be less than num_elements for non-blocking streams. If an error occurs, then an exception is raised. A value of zero is only returned if num_elements is zero.

Return type

int

Raises

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

Examples

Send 4 64-bit double-precision floats immediately by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("d", [1, 2, 3, 4])
>>> num_elements = len(data)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_doubles(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()

Stream.send_double_array(elements, num_elements)

Writes an array of 64-bit double-precision floats to the stream buffer. It attempts to store the double-precision floats in the stream buffer. It differs from the send_doubles function in that it treats the entire array as an atomic unit. 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. The data is not written to the actual communication channel until the stream is flushed using flush or there is no more room available in the stream buffer. If an error occurs, then it throws an exception.

Unlike the send_doubles function, the size of the stream send buffer must be at least as large as the number of bytes being sent.

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. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time flush is called or there is no more room available in the stream buffer. 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 array is sent successfully. If the array could not be sent without blocking, then it returns 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 sending or flushing 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 containing the data to be sent.
num_elements (int) – The number of 64-bit double-precision floats to send from the buffer.

Returns

Returns 1 on success. 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.

Examples

Send 4 64-bit double-precision floats atomically by writing them to the stream and then flushing the buffer.

>>> import struct
>>> from quanser.communications import Stream
>>> elements = array("d", [1, 2, 3, 4])
>>> num_elements = len(elements)
>>> stream = Stream()
>>> stream.connect("tcpip://localhost:5000", False, 64, 64)
>>> try:
>>>   elements_written = stream.send_double_array(elements, num_elements)
>>>   stream.flush()
>>>   # ...
...
>>>   stream.shutdown()
>>> finally:
>>>   stream.close()