Pipe Protocol

The bidirectional pipe communications protocol supports communications over local Unix domain sockets (Unix variants) or named pipes (Windows).

Syntax

pipe:name?option=value,...          % Use a local pipe named "name"
pipe://server/name?option=value,... % Use a named pipe named "name" on server "server" (Windows only)
    

Description

The bidirectional pipe communications protocol supports communications over local Unix domain sockets (Unix variants) or named pipes (Windows). It is identified by using pipe as the protocol name in a URI. The pipe communications protocol may be used to communicate between applications on the same computer. On Windows targets, it may also be used to communicate between computers. It may also be used for communicating between models running in a real-time kernel under Windows and a Windows application. It has the principal benefit that the Windows application does not have to have any knowledge of the real-time kernel and the same protocol may be used with the QUARC Windows target.

The pipe URI takes the form:

pipe:name

where name is the name of the pipe. On Windows targets, it may also take the form:

pipe://server/name

where name is the name of the pipe and server is the name of the machine running the server-side of the pipe.

The name of the pipe should not include forward or back slashes, and should be valid as a filename on the target operating system. On Unix variants, the full name of the pipe will be /var/pipes/<pipename>. For example, the URI pipe://mypipe creates a local domain socket with the full path of /var/pipes/mypipe.

On Windows, or real-time kernels running under Windows, the full name of the pipe will be \\.\pipe\<pipename>. If a server is specified using the second form of the URI, then the full name of the pipe will be \\server\pipe\<pipename>. For example, the URI pipe:mypipe creates a named pipe with the full name of \\.\pipe\mypipe, while the URI pipe://remhost/mypipe creates a named pipe with the full name of \\remhost\pipe\mypipe.

The port in the URI is not used and should be omitted.

For listening streams, the pipe name should not be used by other components in the system. In particular, two models cannot share the same pipe name if they will be running at the same time on the same target because models establish a listening named pipe based on the pipe name specified in the model URI. However, the format specifier "%m" may be used in place of the pipe name. It substitutes the name of the model for the pipe name. For example, the URI pipe:%m refers to a pipe with the same name as the model. 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.

Limitations

Reserved pipe names

Sharing of pipe name

Applications cannot listen on the same pipe name if they will be running at the same time on the same target. The second application will fail to establish a listening connection.

Polling restrictions

The pipe protocol on the Windows target can only poll for data available to receive or client connections ready to be accepted. It cannot poll for space available in the pipe buffer to send data. Attempting to do so will return success whether there is space available or not. 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.

Send and receive buffer sizes

The target operating system may limit the send and receive buffers to a specific range of values. Also, setting the send and/or receive buffer sizes to a value less than the system default has been known to cause severe performance degradation on some systems.

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 pipe send and receive buffers. Setting this option is equivalent to setting both the sndsize and rcvsize options to this value. If none of these options are set then the system default is used. For the Windows target, this option is only supported on the server-side.

sndsize

Set this option to set the size of the pipe send buffer. If this option is not set then the system default is used. For the Windows target, this option is only supported on the server-side.

rcvsize

Set this option to set the size of the pipe receive buffer. If this option is not set then the system default is used. For the Windows target, this option is only supported on the server-side.

close_timeout

When a pipe connection is closed, the pipe 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 network 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 network 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.

Unlike the shared memory driver, this timeout is not used if the stream_shutdown function has been called and a receive operation is called locally. In this case, the receive operation will only block for up to certain amount of time before the pipe notifies it that an error has occurred because the peer is not closing its end of the connection. However, this timeout is determined by the operating system and can be 30 to 60 seconds long or longer.

Driver

The driver supporting pipe communications is called qrt_pipe.

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.