enque Kernel Service

Purpose

Sends a request queue element to a device queue.

Syntax

#include <sys/types.h> #include <sys/errno.h> #include <sys/deviceq.h> int enque ( qe) struct req_qe *qe;

Parameter

Description

The enque kernel service is not part of the base kernel, but is provided by the device queue management kernel extension. This queue management kernel extension must be loaded into the kernel before loading any kernel extensions referencing these services.

The enque service places the queue element into a specified device queue. It is used for simple process-to-process communication within the kernel. The requester builds a copy of the queue element, indicated by the qe parameter, and passes this copy to the enque service. The kernel copies this queue element into a queue element in pinned global memory and then enqueues it on the target device queue.

The path identifier in the request queue element indicates the device queue into which the element is placed.

The enque service supports the sending of the following types of queue elements:

For simple interprocess communication, general purpose queue elements are used.

The queue element priority value can range from QE_BEST_PRTY to QE_WORST_PRTY. This value is limited to the value specified when the queue was created.

The operation options in the queue element control how the queue element is processed. There are five standard operation options:

With the SYNC_REQUEST synchronous request option, control does not return from the enque service until the request queue element is acknowledged. This performs in one step what can also be achieved by sending a queue element with the ACK_COMPLETE flag on, and then calling either the et_wait or waitq kernel services.

The kernel calls the server's check routine, if one is defined, before a queue element is placed on the device queue. This routine can stop the operation if it detects an error.

The kernel notifies the device queue's server, if necessary, after a queue element is placed on the device queue. This is done by posting the server process (using the et_post kernel service) with an event control bit.

Execution Environment

The enque kernel service can be called from the process environment only.

Return Values

All other error values represent errors returned by the server.