server_queue_cycle()

int server_queue_cycle(server_queue_t *queue, void **foo)

Attempts to trade the supplied queue entry in *foo for the entry at the front of the queue, if any.

Returns 0 on error or when the queue is empty, if 0 was returned, nothing was done, foo is left alone, your object is still intact.

Returns 1 on success, what foo points at has been replaced with the new object pointer.

You supply the queue you want to work with, and foo points at the pointer to the object you wish to put on the queue. Like every other call in the server_queue API, if you used a SERVER_QUEUE_ENTRY_SUPPLIED queue instead of foo pointing at some opaque object it must point at a server_queue_entry_t, and the foo member of the server_queue_entry_t would point at the opaque payload object.

The function will also store the new payload at the supplied location in foo. This means, when it returns 1, what foo pointed at has been overwritten with a new pointer ready for your use.

As mentioned above at the beginning of the queue section, this function takes an entry from the front of the queue, gives you the payload, takes the payload you provided, assigns it to the entry it just took from the front, and places the entry at the back of the queue.