Shared Memory Protocol

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

Syntax

shmem://name:port?option=value,... % Commmunicate 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. In particular, it does not support communications between Windows and a real-time kernel such as RTX or INTime. There are other specialized protocols, such as inmem for that purpose.

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.

For listening streams, the combination of hostname and port should not be used by other components in the system. In particular, two models cannot share the same hostname and port number if they will be running at the same time on the same target because models establish a listening shared memory connection based on the hostname and port specified in the model URI. However, the format specifier "%m" may be used in place of the hostname. It substitutes the hostname for the name of the model. For example, the URI shmem://%m:1 refers to a shared memory buffer with the same name as the model and using port 1. Since two Simulink diagrams with the same name cannot be opened at the same time in a single Matlab session, this URI guarantees that models always have a unique URI. This URI is the default model URI for the Windows target since the host machine is expected to be the same as the target machine.

Limitations

Sharing of shared memory hostname and port

Applications cannot share the same combination of hostname and port if they will be running at the same time on the same target. The second application will fail to establish a listening connection.

Shared memory under Windows Vista and above

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 Vista or above, processes must have SeCreateGlobalPrivilege rights in order to create shared memory in the global namespace. By default, only administrators and services have this privilege.

QUARC ensures that the QUARC Target Manager and QUARC models have the necessary rights to create shared memory in the global namespace. Hence, shared memory may be used to communicate with the QUARC Target Manager or QUARC models.

However, the QUARC stream commands in MATLAB may not be used to create a listening shared memory stream that will communicate with a model unless MATLAB is run with the necessary SeCreateGlobalPrivilege rights. These rights are available if MATLAB 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 MATLAB however, because the client-side does not create global shared memory buffers. The same restriction applies to user applications using the stream API. See the local option for more information.

An alternative to using local or global shared memory buffers that is more flexible is to use a private namespace via the private option. Shared memory in a private namespace can be created by real-time code or non-real-time code or scripts without requiring special privileges. This makes it ideal for communicating between models and other applications. Use of a private namespace is recommended in these situations.

The value of the private option is the name of the private namespace. Two peers communicating over shared memory using a private namespace must specify the same name for the private namespace. Shared memory with the same hostname and port cannot communicate if the private namespace is different because the hostname and port are within the scope of the private namespace.

Polling restrictions

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 stream_connect or stream_accept functions 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 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. Local shared memory may be created without SeCreateGlobalPrivilege rights but it can only be accessed within the current interactive session and is not visible to models run by the QUARC Target Manager on Windows Vista or above. However, it can be used to communicate between a MATLAB 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.

private

Set this option to the name of the private namespace. Short names are preferable. The private namespace defines the scope of the shared memory hostname and port so that only a peer using the same private namespace can see the shared memory. Shared memory using a private namespace can be created in real-time code or outside real-time code (e.g. in MATLAB scripts or applications). Hence, it is ideal for communicating between real-time code and applications and is recommended for those situations.

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

See Also

• Communications
• QUARC Communications Protocols
• Communications Using the C Language

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.