queues.h File Reference

Task execution queue interfaces. More...

#include "gate/gate_core_api.h"
#include "gate/streams.h"
#include "gate/strings.h"
#include "gate/times.h"

Macros
#define	GATE_DATAQUEUE_RESULT_OPEN   1
#define	GATE_DATAQUEUE_RESULT_OPENNEW   2
#define	GATE_DATAQUEUE_RESULT_CLOSE   3
#define	GATE_DATAQUEUE_RESULT_READ   4
#define	GATE_DATAQUEUE_RESULT_WRITE   5
#define	GATE_DATAQUEUE_RESULT_ERROR   6
#define	GATE_DATAQUEUE_RESULT_HEARTBEAT   255
#define	GATE_MSGQUEUE_MESSAGETYPE_IDRANGE   0x00ffffff
#define	GATE_MSGQUEUE_MESSAGETYPE_FLAGRANGE   0xff000000
#define	GATE_MSGQUEUE_MESSAGETYPE_OBJECT_FLAG   0x01000000
#define	GATE_MSGQUEUE_MESSAGETYPE_SYNC_FLAG   0x02000000

Typedefs
typedef struct gate_queueitembuffer_class *	gate_queueitembuffer_t

Functions
GATE_CORE_API gate_queueitembuffer_t	gate_queueitembuffer_create (gate_size_t max_length, gate_size_t item_size, gate_mem_copyctor_t item_cctor, gate_mem_dtor_t item_dtor)
	Creates a new queue-item-buffer object.
GATE_CORE_API gate_result_t	gate_queueitembuffer_destroy (gate_queueitembuffer_t buffer)
	Destroys and releases all internal sources of a queue-item-buffer.
GATE_CORE_API gate_size_t	gate_queueitembuffer_length (gate_queueitembuffer_t buffer)
	Returns the current amount of items in the queue buffer.
GATE_CORE_API gate_result_t	gate_queueitembuffer_push (gate_queueitembuffer_t buffer, void const *item_input)
	Adds a new item to the queue buffer and wakes up all waiting pop() invokes to retrieve data.
GATE_CORE_API gate_result_t	gate_queueitembuffer_pop (gate_queueitembuffer_t buffer, gate_uint32_t wait_timeout_ms, void *item_output, gate_size_t item_size)
	Adds a new item to the queue buffer and wakes up all waiting pop() invokes to retrieve data.
GATE_CORE_API gate_result_t	gate_exequeue_create (gate_exequeue_t *queue, gate_entrypoint_t init_task, gate_entrypoint_t shutdown_task, void *task_param)
	Creates a new code execution queue in a separate worker thread.
GATE_CORE_API gate_result_t	gate_exequeue_destroy (gate_exequeue_t queue)
	Shuts down the execution queue's worker thread and releases all resources.
GATE_CORE_API gate_result_t	gate_exequeue_push (gate_exequeue_t queue, gate_entrypoint_t function_ptr, void *parameter, gate_mem_dtor_t paramdestructor)
	Pushes a new code function onto the back of the execution queue.
GATE_CORE_API gate_result_t	gate_exequeue_itemcount (gate_exequeue_t queue, gate_size_t *items)
	Retrieves the current count of pending items in the execution queue.
GATE_CORE_API gate_msgqueue_t *	gate_memory_msgqueue_create ()
	Creates an in-memory message queue.

Detailed Description

Task execution queue interfaces.

Macro Definition Documentation

GATE_DATAQUEUE_RESULT_OPEN

#define GATE_DATAQUEUE_RESULT_OPEN   1

a channel open request has completed

GATE_DATAQUEUE_RESULT_OPENNEW

#define GATE_DATAQUEUE_RESULT_OPENNEW   2

a new channel was opened (not necessary requested by open())

GATE_DATAQUEUE_RESULT_CLOSE

#define GATE_DATAQUEUE_RESULT_CLOSE   3

a channel was closed

GATE_DATAQUEUE_RESULT_READ

#define GATE_DATAQUEUE_RESULT_READ   4

data read request has completed

GATE_DATAQUEUE_RESULT_WRITE

#define GATE_DATAQUEUE_RESULT_WRITE   5

data write request has completed

GATE_DATAQUEUE_RESULT_ERROR

#define GATE_DATAQUEUE_RESULT_ERROR   6

an error on a channel has occured

GATE_DATAQUEUE_RESULT_HEARTBEAT

#define GATE_DATAQUEUE_RESULT_HEARTBEAT   255

undefined internal event (used as IDLE or PREPARE event)

GATE_MSGQUEUE_MESSAGETYPE_IDRANGE

#define GATE_MSGQUEUE_MESSAGETYPE_IDRANGE   0x00ffffff

allowed bit-range where used defined message IDs can be assigned

GATE_MSGQUEUE_MESSAGETYPE_FLAGRANGE

#define GATE_MSGQUEUE_MESSAGETYPE_FLAGRANGE   0xff000000

bit range of generic flags in the message ID

GATE_MSGQUEUE_MESSAGETYPE_OBJECT_FLAG

#define GATE_MSGQUEUE_MESSAGETYPE_OBJECT_FLAG   0x01000000

data pointer addresses a gate_object_t* instance

GATE_MSGQUEUE_MESSAGETYPE_SYNC_FLAG

#define GATE_MSGQUEUE_MESSAGETYPE_SYNC_FLAG   0x02000000

message needs to be processed synchronous

Typedef Documentation

gate_queueitembuffer_t

typedef struct gate_queueitembuffer_class* gate_queueitembuffer_t

opaque queueitembuffer object handle

Function Documentation

gate_queueitembuffer_create()

GATE_CORE_API gate_queueitembuffer_t gate_queueitembuffer_create	(	gate_size_t	max_length,
		gate_size_t	item_size,
		gate_mem_copyctor_t	item_cctor,
		gate_mem_dtor_t	item_dtor )

Creates a new queue-item-buffer object.

Parameters

[in]	max_length	Maximum allowed count of items in buffer, 0 means infinite
[in]	item_size	object size of one item in bytes (sizeof(ITEM))
[in]	item_cctor	optional copy-constructor function pointer to create new items in queue buffer
[in]	item_dtor	optional destructor function pointer to release items in queue buffer

Returns

new queue-item-buffer object pointer or NULL in error cases

gate_queueitembuffer_destroy()

GATE_CORE_API gate_result_t gate_queueitembuffer_destroy

(

gate_queueitembuffer_t

buffer

)

Destroys and releases all internal sources of a queue-item-buffer.

Parameters

[in]

buffer

queue-item-buffer object handle

Returns

GATE_RESULT_* result codes

gate_queueitembuffer_length()

GATE_CORE_API gate_size_t gate_queueitembuffer_length

(

gate_queueitembuffer_t

buffer

)

Returns the current amount of items in the queue buffer.

Parameters

[in]

buffer

queue-item-buffer object handle

Returns

current amount of items in the buffer

gate_queueitembuffer_push()

GATE_CORE_API gate_result_t gate_queueitembuffer_push	(	gate_queueitembuffer_t	buffer,
		void const *	item_input )

Adds a new item to the queue buffer and wakes up all waiting pop() invokes to retrieve data.

Parameters

[in]	buffer	queue-item-buffer object handle
[in]	item_input	pointer to item to be added

Returns

GATE_RESULT_* result codes

gate_queueitembuffer_pop()

GATE_CORE_API gate_result_t gate_queueitembuffer_pop	(	gate_queueitembuffer_t	buffer,
		gate_uint32_t	wait_timeout_ms,
		void *	item_output,
		gate_size_t	item_size )

Adds a new item to the queue buffer and wakes up all waiting pop() invokes to retrieve data.

Parameters

[in]	buffer	queue-item-buffer object handle
[in]	wait_timeout_ms	maximum time im milliseconds to wait for an item or GATE_QUEUEITEMBUFFER_WAIT_INFINITE
[out]	item_output	pointer to raw memory where a copy of the item is allocated/constructed
[in]	item_size	size of memory pointed to by item_output

Returns

GATE_RESULT_* result codes

gate_exequeue_create()

GATE_CORE_API gate_result_t gate_exequeue_create	(	gate_exequeue_t *	queue,
		gate_entrypoint_t	init_task,
		gate_entrypoint_t	shutdown_task,
		void *	task_param )

Creates a new code execution queue in a separate worker thread.

Parameters

queue	Pointer to exeuction queue type to be filled with new handle
init_task	optional function pointer to code to be executed when the queue thread is starting
shutdown_task	optional function pointer to code to be executed when the queue thread is terminating
task_param	optional parameter which is dispatched to init_task() and shutdown_task() functions

Returns

result code (see GATE_RESULT_*)

gate_exequeue_destroy()

GATE_CORE_API gate_result_t gate_exequeue_destroy

(

gate_exequeue_t

queue

)

Shuts down the execution queue's worker thread and releases all resources.

Parameters

queue

Execution queue handle to be destroyed

Returns

result code (see GATE_RESULT_*)

gate_exequeue_push()

GATE_CORE_API gate_result_t gate_exequeue_push	(	gate_exequeue_t	queue,
		gate_entrypoint_t	function_ptr,
		void *	parameter,
		gate_mem_dtor_t	paramdestructor )

Pushes a new code function onto the back of the execution queue.

Parameters

queue	Execution queue handle where new task is pushed to
function_ptr	Pointer to function to be executed in the queue's workerthread
parameter	optional parameter pointer to be dispatched to the function which is going to be executed
paramdestructor	optional destructur function pointer that is applied to the parameter argument after execution of function_ptr

Returns

result code (see GATE_RESULT_*)

gate_exequeue_itemcount()

GATE_CORE_API gate_result_t gate_exequeue_itemcount	(	gate_exequeue_t	queue,
		gate_size_t *	items )

Retrieves the current count of pending items in the execution queue.

Parameters

queue	Exeuction queue handle to be accessed
items	pointer to counter variable to be filled with the current number of pending items in the queue

Returns

result code (see GATE_RESULT_*)

gate_memory_msgqueue_create()

GATE_CORE_API gate_msgqueue_t * gate_memory_msgqueue_create

(

)

Creates an in-memory message queue.

Returns

Pointer to new allocated msgqueue_t object