server_queue_free()

int server_queue_free(server_queue_t *queue)

Frees the queue, this must be called with an empty queue. That is, you must have pulled or acquired all the entries before trying to free it. Of course it would be possible to have server_queue_free() walk the resident queue entries and unref them, but the assumption is that something needs to be done with the payload resources. Since the queue has no knowledge of payload-specific semantics, it's difficult to support this cleanly, and would probably just result in buggy programs.

Returns 1 on success, and 0 on failure.

Error means either you passed a NULL value as the queue, or you passed a queue that was non-empty. When 0 is returned, the queue is left as-is, possibly keeping it functional and the free can be tried again. It is not recommended that you design your program around this behavior as if it is normal, and ServerKit will complain via stderr every time you cause these errors.

After successfully freeing a queue you may not use it again. If you happen to have server_queue_entry_t instances acquired before the server_qeueu_free() call, they are unaffected by the free. Once you have called server_heap_unit_unref() on all acquired queue entries the orinating heap will get freed automatically.

This happens because when you free the queue, the internal transport heap is also freed with server_heap_free(). If you look at the semantics of server_heap_free() explained in this document, you'll see mentioned that server_heap_free() will defer the actual heap freeing if there are any outstanding unit references.