ChannelCreate(), ChannelCreate_r()

Create a communications channel

Synopsis:

#include <sys/neutrino.h>

int ChannelCreate( unsigned flags );

int ChannelCreate_r( unsigned flags );

Arguments:

flags

Flags that can be used to request notification pulses from the kernel or request other changes in behavior; a combination of the following:

• _NTO_CHF_COID_DISCONNECT
• _NTO_CHF_DISCONNECT
• _NTO_CHF_FIXED_PRIORITY
• _NTO_CHF_NET_MSG
• _NTO_CHF_REPLY_LEN
• _NTO_CHF_SENDER_LEN
• _NTO_CHF_THREAD_DEATH
• _NTO_CHF_UNBLOCK

For more information, see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The ChannelCreate() and ChannelCreate_r() kernel calls create a channel that can be used to receive messages and pulses. Once created, the channel is owned by the process and isn't bound to the creating thread.

These functions are identical, except in the way they indicate errors. See the Returns section for details.

Threads wishing to communicate with the channel attach to it by calling ConnectAttach(). The threads may be in the same process, or in another process on the same node (or a remote node if the network manager is running).

---

If a process wants other processes to communicate with it, it typically uses name_attach() to create a channel and associate a name with it, and the sender process uses name_open() to locate that name and create a connection to it.

---

Once attached, these threads use MsgSendv() or MsgSendPulse() to enqueue messages and pulses on the channel. Messages and pulses are enqueued in priority order.

To dequeue and read messages and pulses from a channel, use MsgReceivev(). Any number of threads may call MsgReceivev() at the same time, in which case they block and queue (if no messages or pulses are waiting) for a message or pulse to arrive. A multi-threaded I/O manager typically creates multiple threads and has them all RECEIVE-blocked on the channel.

The return value of ChannelCreate() is a channel ID, an int taken from a channel vector on the process. Most managers use a single channel for most, if not all, their communications with clients. Additional channels can be used as special channels for information.

By default, when a message is received from a channel, the thread priority of the receiver is set to match that of the thread that sent the message. This basic priority inheritance prevents priority inversion. If a message arrives at a channel and there's no thread waiting to receive it, the system boosts (if necessary) all threads in the process that have received a message from the channel in the past. This boost prevents a priority inversion of the client in the case where all threads are currently working on behalf of other clients, perhaps at a lower priority. When a thread is first created, it isn't associated with a channel until it does a MsgReceivev() on it. In the case of multiple channels, a thread is associated with the last channel it received from.

After receiving a message, a thread can dissociate itself from the channel by calling MsgReceivev() with a -1 for the channel ID. Priority inheritance can be disabled by setting _NTO_CHF_FIXED_PRIORITY in the flags argument. In this case a thread's priority isn't affected by messages it receives on a channel.

A manager typically involves the following loop. There may be one or more threads in the loop at a time. Note that your program (not each thread) should call ChannelCreate() only once.

iov_t iov;
...
SETIOV( &iov, &msg, sizeof( msg ) );
...
chid = ChannelCreate(flags);
...
for(;;) {
    /*
     Here's a one-part message; you could just as
     easily receive a 20-part message by filling in the
     iov appropriately.
    */
    rcvid = MsgReceivev(chid, &iov, 1, &info);

    /* msg is filled in by MsgReceivev() */
    switch(msg.type) {
        ...
    }

    /* iov could be filled in again to point to a new message */
    MsgReplyv(rcvid, iov, 1);
}

Some of the channel flags in the flags argument request changes from the default behavior; others request notification pulses from the kernel. The pulses are received by MsgReceivev() on the channel and are described by a _pulse structure.

The channel flags and (where appropriate) associated values for the pulse's code and value are described below.

_NTO_CHF_COID_DISCONNECT

Pulse code:

_PULSE_CODE_COIDDEATH

Pulse value:

Connection ID (coid) of a connection that was attached to a destroyed channel.

Deliver a pulse to this channel for each connection that belongs to the calling process when the channel that the connection is attached to is destroyed. Only one channel per process can have this flag set.

---

If a channel has one or both of _NTO_CHF_COID_DISCONNECT or _NTO_CHF_THREAD_DEATH set, neither flag may be set for any other channel in the process.

---

_NTO_CHF_DISCONNECT

Pulse code:

_PULSE_CODE_DISCONNECT

Pulse value:

None

Deliver a pulse when all connections from a process are detached (e.g. close(), ConnectDetach(), name_close()). If a process dies without detaching all its connections, the kernel detaches them from it. When this flag is set, the server must call ConnectDetach( scoid ) where scoid is the server connection ID in the pulse message. Failure to do so leaves an invalid server connection ID that can't be reused. Over time, the server may run out of available IDs. If this flag isn't set, the kernel removes the server connection ID automatically, making it available for reuse.

_NTO_CHF_FIXED_PRIORITY

Suppress priority inheritance when receiving messages. Receiving threads won't change their priorities to those of the sending threads. If you're using adaptive partitioning, the receiving threads won't run in the sending threads' partitions.

_NTO_CHF_NET_MSG

Reserved for the io_pkt* resource manager.

_NTO_CHF_REPLY_LEN

Request that the length of the reply be included in the dstmsglen member of the _msg_info structure that MsgReceivev() fills in. The dstmsglen member is valid only if you set this channel flag when you create the channel.

_NTO_CHF_SENDER_LEN

Request that the length of the source message be included in the srcmsglen member of the _msg_info, structure that MsgReceivev() fills in. The srcmsglen member is valid only if you set this channel flag when you create the channel.

_NTO_CHF_THREAD_DEATH

Pulse code:

_PULSE_CODE_THREADDEATH

Pulse value:

Thread ID (tid)

Deliver a pulse on the death of any thread in the process that owns the channel. Only one channel per process can have this flag set.

---

If a channel has one or both of _NTO_CHF_COID_DISCONNECT or _NTO_CHF_THREAD_DEATH set, neither flag may be set for any other channel in the process.

---

_NTO_CHF_UNBLOCK

Pulse code:

_PULSE_CODE_UNBLOCK

Pulse value:

Receive ID (rcvid)

---

In most cases, you'll set the _NTO_CHF_UNBLOCK flag.

---

Deliver a pulse when a thread that's REPLY-blocked on a channel attempts to unblock before its message is replied to. This occurs between the time of a MsgReceivev() and a MsgReplyv() by the server. The sending thread may be unblocked because of a signal or a kernel timeout.

If the sending thread unblocks, MsgReplyv() fails. The manager may not be in a position to handle this failure. It's also possible that the client will die because of the signal and never send another message. If the manager is holding onto resources for the client (such as an open file), it may want to receive notification that the client wants to break out of its MsgSendv().

Setting the _NTO_CHF_UNBLOCK bit in flags prevents a thread that's in the REPLY-blocked state from unblocking. Instead, a pulse is sent to the channel, informing the manager that the client wishes to unblock. In the case of a signal, the signal will be pending on the client thread. When the manager replies, the client is unblocked and at that point, any pending signals are acted upon. From the client's point of view, its MsgSendv() will have completed normally and any signal will have arrived on the opcode following the successful kernel call.

When the manager receives the pulse, it can do one of these things:

• If it believes that it will be replying shortly, it can discard the pulse, resulting in a small latency in the unblocking, or it can signal the client. A short blocking request to a filesystem often takes this approach.
• If the reply is going to take some time or an unknown amount of time, the manager should cancel the current operation and reply back with an error or whatever data is available at this time in the reply message to the client thread. A request to a device manager waiting for input would take this approach.

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

ChannelCreate()

The channel ID of the newly created channel. If an error occurs, the function returns -1 and sets errno.

ChannelCreate_r()

The channel ID of the newly created channel. This function does NOT set errno. If an error occurs, the function returns the negative of a value from the Errors section.

Errors:

EAGAIN

All kernel channel objects are in use.

EBUSY

The _NTO_CHF_COID_DISCONNECT or the _NTO_CHF_THREAD_DEATH flag was given and another channel belonging to this process already has the same flag set.

Classification:

QNX Neutrino

See also:

ChannelDestroy(), close(), ConnectAttach(), ConnectDetach(), _msg_info, MsgReceivev(), MsgReplyv(), MsgSendv(), MsgSendPulse(), name_attach(), name_close(), name_open(), _pulse

Message Passing chapter of Getting Started with QNX Neutrino