Shared Memory Protocol :: RCP Communications Protocols

navigation bar

Table of Contents >Quanser Rapid Control Prototyping Toolkit >Communication Protocols >

Shared Memory Protocol

The shared memory protocol supports communications through shared memory on the same machine.

Syntax

shmem://name:port?option=value,... % Communicate via shared memory called "name" on port "port"

Description

The shared memory communications protocol supports communications through shared memory. It is identified by using shmem as the protocol name in a URI. It cannot be used to communicate between two operating systems running on the same machine.

The hostname in the URI is used as the name of the shared memory. The name is extended internally so that a shared memory server can accept connections from multiple clients, much like TCP/IP sockets, with each client getting its own unique connection.

The port in the URI determines the "port" used for communications. The port is used as part of the shared memory name so that URI's with the same hostname but different ports refer to different shared memory channels. For example, the URI shmem://my-memory:2 refers to a shared memory buffer called my-memory listening on port 2. The default port number is 1.

Limitations

Shared memory under Windows 7 or Later Versions

Warning The shared memory protocol is structured such that only the server-side of a connection creates shared memory buffers (stream_listen and stream_accept). On Windows 7 or later versions, processes must have SeCreateGlobalPrivilege rights in order to create shared memory in the global namespace. By default, only administrators and services have this privilege.

However, the RCP stream commands in LabVIEW may not be used to create a listening shared memory stream that will communicate with a VI unless LabVIEW is run with the necessary SeCreateGlobalPrivilege rights. These rights are available if LabVIEW is run as administrator or the user account rights are modified to include the SeCreateGlobalPrivilege rights.

The client-side of a stream (stream_connect) may still be established in LabVIEW however, because the client-side does not create global shared memory buffers. The same restriction applies to user applications using the Quanser Stream API. See the local option for more information.

Polling restrictions

Warning Listening streams can only poll for client connections ready to be accepted, because listening streams cannot send or receive data. Likewise, streams created with the CL Stream Connect or CL Stream Accept VIs cannot poll for pending client connections because such streams are not listening streams.

Options

backlog

Set this option to the number of client connections that may be pending on a listening connection. Client connections are queued until the connection is accepted. The backlog parameter determines the length of this queue. This parameter is only used for listening connections and is ignored otherwise.

timeout

Set this option to the timeout interval to use for blocking CL Stream Connect calls. The default timeout interval is five seconds. If a connection cannot be established within the timeout interval then the connection attempt fails.

memsize

Set this option to set the size of the shared memory send and receive buffers. The default buffer size is approximately 32K bytes. Setting this option is equivalent to setting both the sndsize and rcvsize options to this value.

sndsize

Set this option to set the size of the shared memory send buffer. The default buffer size is approximately 32K bytes.

rcvsize

Set this option to set the size of the shared memory receive buffer. The default buffer size is approximately 32K bytes.

local

Set this option to 1 to use shared memory that is local to the current logon session rather than shared memory in the global namespace. However, it can be used to communicate between a LabVIEW session and a user application, for example, running in the same logon session. The default value for this option is 0, indicating that the shared memory is to be created in the global namespace.

close_timeout

When a shared memory connection is closed, the shared memory driver attempts to perform a graceful shutdown by first disabling send operations locally and then entering a loop to receive data from the peer. Shutting down send operations locally notifies the peer that no more data will be sent so the peer's receive operations will return any remaining data in the shared memory buffer and then return 0 to indicate that the connection has been closed at the other end. The peer then performs a graceful shutdown also, so that the receive loop at this end finishes receiving any remaining data in the shared memory buffer and then exits the loop and closes the connection. In this way, the local receive loop prevents any send operations at the peer from blocking or returning an error, and both ends of the connection close gracefully and no errors are returned. However, if the peer is misbehaving and never does a receive operation, so that it never detects that our end has begun closing the connection, then the receive loop at our end would block indefinitely. To prevent this situation, this loop is timed. If a receive operation in this loop takes more than the time period specified in the close_timeout option then the loop exits and the connection is closed forcefully. Send operations at the peer, in this case, will return a QERR_CONNECTION_SHUTDOWN error indicating that the connection has been shutdown ungracefully. This timeout is also used if the stream_shutdown function has been called and a receive operation is called locally. The receive operation will only block for up to the close_timeout period once the connection has been shutdown. If the timeout expires then the receive operation will return a QERR_PEER_IGNORING_SHUTDOWN error.

Driver

The driver supporting shared memory communications is called qrt_shmem.

Targets

Target	Supported	Comments
RCP Windows (64-bit) Target	Yes	Fully supported.