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_QUEUEITEMBUFFER_WAIT_INFINITE   0xffffffff
#define	GATE_INTERFACE_NAME_DATAQUEUE   GATE_INTERFACE_NAME_OBJECT GATE_INTERFACE_NAME_SEPARATOR "dataqueue"
#define	GATE_QUEUE_INVALID_ID   ((gate_channel_id_t)(-1))
#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_dataqueue_start(objptr, status_callback, callback_data)    ((gate_dataqueue_t*)(objptr))->vtbl->start(((gate_dataqueue_t*)(objptr)), status_callback, callback_data)
#define	gate_dataqueue_stop(objptr)    ((gate_dataqueue_t*)(objptr))->vtbl->stop(((gate_dataqueue_t*)(objptr)))
#define	gate_dataqueue_open(objptr, address, flags, user_param, channel_id)    ((gate_dataqueue_t*)(objptr))->vtbl->open(((gate_dataqueue_t*)(objptr)), address, flags, user_param, channel_id)
#define	gate_dataqueue_close(objptr, channel_id)    ((gate_dataqueue_t*)(objptr))->vtbl->close(((gate_dataqueue_t*)(objptr)), channel_id)
#define	gate_dataqueue_begin_read(objptr, channel_id, size, user_param)    ((gate_dataqueue_t*)(objptr))->vtbl->begin_read(((gate_dataqueue_t*)(objptr)), channel_id, size, user_param)
#define	gate_dataqueue_begin_write(objptr, channel_id, buffer, buffer_size, user_param)    ((gate_dataqueue_t*)(objptr))->vtbl->begin_write(((gate_dataqueue_t*)(objptr)), channel_id, buffer, buffer_size, user_param)
#define	GATE_INTERFACE_NAME_MSGQUEUE   GATE_INTERFACE_NAME_STARTABLE GATE_INTERFACE_NAME_SEPARATOR "msgqueue"
#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
#define	GATE_MSGQUEUE_MAKE_MESSAGETYPE(flags, id)   (((gate_uint32_t)flags & GATE_MSGQUEUE_MESSAGETYPE_FLAGRANGE) | ((gate_uint32_t)id & GATE_MSGQUEUE_MESSAGETYPE_IDRANGE))
#define	GATE_MSGQUEUE_GET_MESSAGETYPE_ID(type)   ((gate_uint32_t)type & GATE_MSGQUEUE_MESSAGETYPE_IDRANGE)
#define	GATE_MSGQUEUE_GET_MESSAGETYPE_FLAGS(type)   ((gate_uint32_t)type & GATE_MSGQUEUE_MESSAGETYPE_FLAGRANGE)
#define	GATE_MSGQUEUE_STATUS_OFFLINE   0
#define	GATE_MSGQUEUE_STATUS_STARTING   1
#define	GATE_MSGQUEUE_STATUS_ONLINE   2
#define	GATE_MSGQUEUE_STATUS_STOPPING   3
#define	GATE_MSGQUEUE_STATUS_ERROR   4
#define	gate_msgqueue_add_target(obj, address, ptr_target_id)   (obj)->vtbl->add_target((obj), (address), (ptr_target_id))
#define	gate_msgqueue_get_target(obj, target_id, ptr_address)   (obj)->vtbl->get_target((obj), (target_id), (ptr_address))
#define	gate_msgqueue_resolve_target(obj, address, ptr_target_id)   (obj)->vtbl->resolve_target((obj), (address), (ptr_target_id))
#define	gate_msgqueue_remove_target(obj, target_id)   (obj)->vtbl->remove_target((obj), (target_id))
#define	gate_msgqueue_publish(obj, target_id, message_type, data, length)   (obj)->vtbl->publish((obj), (target_id), (message_type), (data), (length))
#define	gate_msgqueue_subscribe(obj, target_id, receiver, user_param, ptr_subscriber)   (obj)->vtbl->subscribe((obj), (target_id), (receiver), (user_param), (ptr_subscriber))
#define	gate_msgqueue_unsubscribe(obj, subscriber)   (obj)->vtbl->unsubscribe((obj), (subscriber))

Typedefs
typedef struct gate_queueitembuffer_class *	gate_queueitembuffer_t
typedef void *	gate_exequeue_t
typedef gate_uintptr_t	gate_channel_id_t
typedef void(*	gate_dataqueue_status_t) (void *callback_data, gate_uint32_t result_type, gate_channel_id_t channel_id, gate_result_t result_code, char const *buffer, gate_size_t buffer_length, void *user_param)
typedef gate_uintptr_t	gate_msgqueue_target_id_t
typedef gate_uintptr_t	gate_msgqueue_subscription_id_t
typedef void(*	gate_msgqueue_receiver_t) (GATE_INTERFACE_STRUCT(gate_msgqueue) *msgqueue, gate_msgqueue_target_id_t target_id, gate_uint32_t message_type, void const *data, gate_size_t length, void *user_param)

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_INTERFACE_STRUCT (gate_dataqueue)
GATE_CORE_API int	gate_compare_channel_id (void const *item1, void const *item2)
	GATE_INTERFACE (gate_dataqueue)
	GATE_INTERFACE_STRUCT (gate_msgqueue)
	GATE_INTERFACE (gate_msgqueue)
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_CLOSE

#define GATE_DATAQUEUE_RESULT_CLOSE   3

a channel was closed

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_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_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_MSGQUEUE_MESSAGETYPE_FLAGRANGE

#define GATE_MSGQUEUE_MESSAGETYPE_FLAGRANGE   0xff000000

bit range of generic flags in the message ID

GATE_MSGQUEUE_MESSAGETYPE_IDRANGE

#define GATE_MSGQUEUE_MESSAGETYPE_IDRANGE   0x00ffffff

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

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_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_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_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_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

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_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_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

Returns

GATE_RESULT_* result codes