ArbCmd queues

Some interfaces allow multiple commands to be specified. This is done through command queue objects.

Constructing a command queue

To construct a command queue, create a handle using dqcs_cq_new(), and then push ArbCmd objects into it one by one using dqcs_cq_push(). To keep the API simple, it is not possible to insert by index or override previously added commands

dqcs_cq_new()

Creates a new ArbCmd queue object.

dqcs_handle_t dqcs_cq_new(void)

Returns the handle of the newly created ArbCmd queue. The queue is initially empty. Queues implement a "first-in, first-out" model.

ArbCmd queue objects support the handle, arb, cmd, and cq APIs.

The arb and cmd APIs refer to the ArbCmd at the front of the queue. Use dqcs_cq_next() to remove the front entry, allowing access to the next command.

dqcs_cq_push()

Pushes an ArbCmd object into the given ArbCmd queue.

dqcs_return_t dqcs_cq_push(
    dqcs_handle_t cq,
    dqcs_handle_t cmd
)

This function returns -1 to indicate failure. The ArbCmd object specified by cmd is moved into the queue. That is, the handle is consumed if and only if the function succeeds.

Iterating over a command queue

Command queues can be iterated over as follows (note, only once!):

dqcs_handle_t queue = ...;
for (; dqcs_cq_len(queue) > 0; dqcs_cq_next(queue)) {
    ...
}

Within the loop body, the queue variable can be used as if it's an ArbCmd handle. The iteration happens in the same order in which dqcs_cq_push() was called.

dqcs_cq_len()

Returns the number of ArbCmd objects in the given ArbCmd queue.

ssize_t dqcs_cq_len(dqcs_handle_t cq)

This function returns -1 to indicate failure.

dqcs_cq_next()

Advances an ArbCmd queue to the next command.

dqcs_return_t dqcs_cq_next(dqcs_handle_t cq)

Use the dqcs_arb_* and dqcs_cmd_* interfaces to read out the command before calling this function.

To iterate over a queue in C, use the following snippit:

for (; dqcs_cq_len(queue) > 0; dqcs_cq_next(queue)) {
    dqcs_cmd_...(queue, ...)
    dqcs_arb_...(queue, ...)
}