Data Structures | Typedefs | Functions
Thread Queue Group

These functions provide simple zero-copy message queues for threads. More...

Data Structures

struct  _Eina_Thread_Queue_Msg
 
struct  _Eina_Thread_Queue_Msg_Sub
 

Typedefs

typedef struct _Eina_Thread_Queue Eina_Thread_Queue
 This is a uni-directional zero-copy thread message queue specifically designed with the idea of sending large volumes of messages with no copies from one thread to another (or from/to the mainloop). More...
 
typedef struct _Eina_Thread_Queue_Msg Eina_Thread_Queue_Msg
 This is the minimal header of every message to be put into an Eina Thread Queue. More...
 
typedef struct _Eina_Thread_Queue_Msg_Sub Eina_Thread_Queue_Msg_Sub
 This is a special message type for Eina Thread Queues that have child queues. More...
 

Functions

Eina_Thread_Queueeina_thread_queue_new (void)
 Creates a new thread queue. More...
 
void eina_thread_queue_free (Eina_Thread_Queue *thq)
 Frees a thread queue. More...
 
void * eina_thread_queue_send (Eina_Thread_Queue *thq, int size, void **allocref)
 Allocates a message to send down a thread queue. More...
 
void eina_thread_queue_send_done (Eina_Thread_Queue *thq, void *allocref)
 Finishes sending the allocated message. More...
 
void * eina_thread_queue_wait (Eina_Thread_Queue *thq, void **allocref)
 Fetches a message from a thread queue. More...
 
void eina_thread_queue_wait_done (Eina_Thread_Queue *thq, void *allocref)
 Finishes fetching a message from a thread queue. More...
 
void * eina_thread_queue_poll (Eina_Thread_Queue *thq, void **allocref)
 Fetches a message from a thread queue, but return immediately if there is none with NULL. More...
 
int eina_thread_queue_pending_get (const Eina_Thread_Queue *thq)
 Gets the number of messages on a queue as yet unfetched. More...
 
void eina_thread_queue_parent_set (Eina_Thread_Queue *thq, Eina_Thread_Queue *thq_parent)
 Sets the parent of a thread queue (make this one a child). More...
 
Eina_Thread_Queueeina_thread_queue_parent_get (const Eina_Thread_Queue *thq)
 Gets the parent of a thread queue. More...
 
void eina_thread_queue_fd_set (Eina_Thread_Queue *thq, int fd)
 Sets a file descriptor to write a byte to on a message send. More...
 
int eina_thread_queue_fd_get (const Eina_Thread_Queue *thq)
 Gets the file descriptor written to on message sends. More...
 

Detailed Description

These functions provide simple zero-copy message queues for threads.

Since
1.11

Typedef Documentation

◆ Eina_Thread_Queue

This is a uni-directional zero-copy thread message queue specifically designed with the idea of sending large volumes of messages with no copies from one thread to another (or from/to the mainloop).

The idea is that a thread queue is created and then one or more threads send messages in one end and fetch messages off the other end. If you set a parent message queue to 1 or more queues, then this parent will wake up with a sub queue message, indicating which child queue woke up. This can be used to implement the ability to listen to multiple queues at once.

Since
1.11

◆ Eina_Thread_Queue_Msg

This is the minimal header of every message to be put into an Eina Thread Queue.

Every message has at least this header at the start of the message data, with payload following. You would put this structure as the first struct member of every message type you have, like Eina_Thread_Queue_Msg_Sub does. Messages are always 8 byte aligned within message memory to ensure alignment of all types.

Since
1.11

◆ Eina_Thread_Queue_Msg_Sub

This is a special message type for Eina Thread Queues that have child queues.

This is the only Message type for a parent message queue and it indicates which child queue was woken up with a new message to read. When this message is retrieved, the caller should then also fetch the message from the indicated child queue too.

Since
1.11

Function Documentation

◆ eina_thread_queue_new()

Eina_Thread_Queue* eina_thread_queue_new ( void  )

Creates a new thread queue.

Returns
A valid new thread queue, or NULL on failure
Since
1.11

References eina_semaphore_new(), eina_spinlock_new(), and ERR.

◆ eina_thread_queue_free()

void eina_thread_queue_free ( Eina_Thread_Queue thq)

Frees a thread queue.

This frees a thread queue. It must no longer be in use by anything waiting on messages or sending them. Any pending messages will be freed without being processed by a listener.

Parameters
[in]thqThe thread queue to free
Since
1.11

References eina_semaphore_free(), and eina_spinlock_free().

◆ eina_thread_queue_send()

void* eina_thread_queue_send ( Eina_Thread_Queue thq,
int  size,
void **  allocref 
)

Allocates a message to send down a thread queue.

Parameters
[in,out]thqThe thread queue to allocate the message on
[in]sizeThe size, in bytes, of the message, including standard header
[out]allocrefA pointer to store a general reference handle for the message
Returns
A pointer to the message data to fill in

This allocates space for a new message on the message queue, but does not actually trigger the send. For that you will need to call eina_thread_queue_send_done() to complete the send and trigger the other side. Every message must at least be a Eina_Thread_Queue_Msg in size and have this structure as the first member (first N bytes) of the message.

Since
1.11

References eina_spinlock_release(), and eina_spinlock_take().

Referenced by eina_thread_queue_send_done().

◆ eina_thread_queue_send_done()

void eina_thread_queue_send_done ( Eina_Thread_Queue thq,
void *  allocref 
)

Finishes sending the allocated message.

Parameters
[in,out]thqThe thread queue the message was placed on
[in,out]allocrefThe allocref returned by eina_thread_queue_send()

This completes the send and triggers the thread queue to wake up any listeners.

Since
1.11

References eina_thread_queue_send(), eina_thread_queue_send_done(), and ERR.

Referenced by eina_thread_queue_send_done().

◆ eina_thread_queue_wait()

void* eina_thread_queue_wait ( Eina_Thread_Queue thq,
void **  allocref 
)

Fetches a message from a thread queue.

Parameters
[in,out]thqThe thread queue to fetch the message from
[out]allocrefA pointer to store a general reference handle for the message
Returns
A pointer to the message data

This will fetch the next message to read from the thread queue and return a pointer to it. The message is guaranteed to have an initial Eina_Thread_Queue_Msg member that will indicate size of the message as a whole. This function will wait, if no messages are available to read and block until a new message comes in, then return. When the message is finished with, the caller must use eina_thread_queue_wait_done() to indicate they are done.

Since
1.11

References eina_spinlock_release(), and eina_spinlock_take().

◆ eina_thread_queue_wait_done()

void eina_thread_queue_wait_done ( Eina_Thread_Queue thq,
void *  allocref 
)

Finishes fetching a message from a thread queue.

Parameters
[in,out]thqThe thread queue the message was fetched from
[in,out]allocrefThe allocref returned by eina_thread_queue_wait()

This should be used after eina_thread_queue_wait() or eina_thread_queue_poll() to indicate the caller is done with the message.

Since
1.11

◆ eina_thread_queue_poll()

void* eina_thread_queue_poll ( Eina_Thread_Queue thq,
void **  allocref 
)

Fetches a message from a thread queue, but return immediately if there is none with NULL.

Parameters
[in,out]thqThe thread queue to fetch the message from
[out]allocrefA pointer to store a general reference handle for the message
Returns
A pointer to the message data

This is the same as eina_thread_queue_wait(), but if no messages are available for reading, it immediately returns NULL to the caller, without waiting for a new message to arrive.

See also
eina_thread_queue_wait()
Since
1.11

References eina_spinlock_release(), and eina_spinlock_take().

◆ eina_thread_queue_pending_get()

int eina_thread_queue_pending_get ( const Eina_Thread_Queue thq)

Gets the number of messages on a queue as yet unfetched.

Parameters
[in]thqThe thread queue to query for pending count
Returns
The number of messages waiting to be fetched

This returns the number of messages waiting to be fetched with eina_thread_queue_wait() or eina_thread_queue_poll().

Since
1.11

◆ eina_thread_queue_parent_set()

void eina_thread_queue_parent_set ( Eina_Thread_Queue thq,
Eina_Thread_Queue thq_parent 
)

Sets the parent of a thread queue (make this one a child).

Parameters
[in,out]thqThe thread queue to alter the parent of
[in]thq_parentThe new parent to set

This sets the parent queue where messages will be reported to. This is how you can listen to multiple queues at once - set multiple queues to have the same parent and then just wait on that one parent. This should be done before any messages are read from or written to the queue. To unset a parent, just set the parent to NULL.

Since
1.11

◆ eina_thread_queue_parent_get()

Eina_Thread_Queue* eina_thread_queue_parent_get ( const Eina_Thread_Queue thq)

Gets the parent of a thread queue.

Parameters
[in]thqThe thread queue to get the parent of
Returns
The parent thread queue

This gets the parent set by eina_thread_queue_parent_get(). If no parent is set, NULL is returned.

See also
eina_thread_queue_parent_set()
Since
1.11

◆ eina_thread_queue_fd_set()

void eina_thread_queue_fd_set ( Eina_Thread_Queue thq,
int  fd 
)

Sets a file descriptor to write a byte to on a message send.

Parameters
[in,out]thqThe thread queue to set the file descriptor of
[in]fdThe fd to set, or -1 to unset it

This sets a file descriptor to write to when a message is written to the thread queue. This can be used to glue a thread queue to something like an Ecore_Pipe that can wake up the mainloop and call a callback whenever data is available on the pipe. The number of bytes available will be the number of messages to fetch from the associated thread queue.

You should set this up before anything writes to or reads from this thread queue.

Since
1.11

◆ eina_thread_queue_fd_get()

int eina_thread_queue_fd_get ( const Eina_Thread_Queue thq)

Gets the file descriptor written to on message sends.

Parameters
[in]thqThe thread queue to get the file descriptor of
Returns
The file descriptor set (or -1 if none is set).

This returns the file descriptor set by eina_thread_queue_fd_set() and by default returns -1 (no fd set).

See also
eina_thread_queue_fd_set()
Since
1.11