Linked Queue

Typedefs
typedef amxc_llist_t	amxc_lqueue_t
	The linked queue structure. More...
typedef amxc_llist_it_t	amxc_lqueue_it_t
	The linked queue iterator structure. More...
typedef amxc_llist_it_delete_t	amxc_lqueue_it_delete_t
	Definition of the item delete function. More...

Functions
AMXC_INLINE int	amxc_lqueue_new (amxc_lqueue_t **lqueue)
	Allocates a linked queue. More...
AMXC_INLINE void	amxc_lqueue_delete (amxc_lqueue_t **lqueue, amxc_lqueue_it_delete_t func)
	Frees the previously allocated linked queue. More...
AMXC_INLINE int	amxc_lqueue_init (amxc_lqueue_t *const lqueue)
	Initializes a linked queue. More...
AMXC_INLINE void	amxc_lqueue_clean (amxc_lqueue_t *const lqueue, amxc_lqueue_it_delete_t func)
	Removes all items from the linked queue. More...
AMXC_INLINE int	amxc_lqueue_add (amxc_lqueue_t *const lqueue, amxc_lqueue_it_t *const it)
	Adds an item to the linked queue. More...
AMXC_INLINE amxc_lqueue_it_t *	amxc_lqueue_remove (amxc_lqueue_t *const lqueue)
	Removes the first added item from the queue. More...
AMXC_INLINE size_t	amxc_lqueue_size (const amxc_lqueue_t *const lqueue)
	Calculates the size of the queue, expressed in number of items. More...
AMXC_INLINE bool	amxc_lqueue_is_empty (const amxc_lqueue_t *const lqueue)
	Checks that the linked queue is empty. More...
AMXC_INLINE int	amxc_lqueue_it_init (amxc_lqueue_it_t *const it)
	Initializes a linked queue iterator. More...

Detailed Description

Typedef Documentation

amxc_lqueue_it_delete_t

typedef amxc_llist_it_delete_t amxc_lqueue_it_delete_t

Definition of the item delete function.

A pointer to a delete function is used in the following functions amxc_lqueue_delete, amxc_lqueue_clean

Definition at line 99 of file amxc_lqueue.h.

amxc_lqueue_it_t

typedef amxc_llist_it_t amxc_lqueue_it_t

The linked queue iterator structure.

Definition at line 89 of file amxc_lqueue.h.

amxc_lqueue_t

typedef amxc_llist_t amxc_lqueue_t

The linked queue structure.

Definition at line 82 of file amxc_lqueue.h.

Function Documentation

amxc_lqueue_add()

AMXC_INLINE int amxc_lqueue_add	(	amxc_lqueue_t *const	lqueue,
		amxc_lqueue_it_t *const	it
	)

Adds an item to the linked queue.

If the item is already in a queue, it is removed from that queue.

Note

Make sure that the iterator of the item is at least initialized when it is first used. Initializing an iterator can be done using amxc_lqueue_it_init. An iterator that is already used in a linked queue is considered initialized.

Parameters

lqueue	a pointer to the linked queue structure
it	a pointer to the linked queue item iterator

Returns

returns 0 when the item is added, -1 when there was an error

Definition at line 213 of file amxc_lqueue.h.

                                                                             {
    return amxc_llist_append(lqueue, it);
}

amxc_lqueue_clean()

AMXC_INLINE void amxc_lqueue_clean	(	amxc_lqueue_t *const	lqueue,
		amxc_lqueue_it_delete_t	func
	)

Removes all items from the linked queue.

Removes all items from the linked queue, if a delete function is provided, it is called for each item after it was removed from the queue.

Parameters

lqueue	a pointer to the linked queue structure
func	a pointer to a function that is called to free each item in the linked queue

Definition at line 190 of file amxc_lqueue.h.

                                                                                  {
    amxc_llist_clean(lqueue, func);
}

amxc_lqueue_delete()

AMXC_INLINE void amxc_lqueue_delete	(	amxc_lqueue_t **	lqueue,
		amxc_lqueue_it_delete_t	func
	)

Frees the previously allocated linked queue.

Removes all items from the linked queue, if a delete function is provided, it is called for each item after it was removed from the queue

Frees the allocated memory and sets the pointer to NULL.

Note

Only call this function for linked queues that are allocated on the heap using amxc_lqueue_new

Parameters

lqueue	a pointer to the location where the pointer to the linked queue is stored
func	a pointer to a function that is called to free each item in the linked queue

Definition at line 147 of file amxc_lqueue.h.

                                                                              {
    amxc_llist_delete(lqueue, func);
}

amxc_lqueue_init()

AMXC_INLINE int amxc_lqueue_init

(

amxc_lqueue_t *const

lqueue

)

Initializes a linked queue.

Initializes the linked queue structure. All pointers are reset to NULL. This function is typically called for linked queues that are on the stack. Allocating and initializing a linked queue on the heap can be done using amxc_lqueue_new

Note

When calling this function on an already initialized linked queue, that contains items, the linked queue is reset and all items in the queue are lost. Use amxc_lqueue_clean to remove all items from the queue.

Parameters

lqueue

a pointer to the linked queue structure.

Returns

0 on success. -1 if a NULL pointer is given.

Definition at line 173 of file amxc_lqueue.h.

                                                  {
    return amxc_llist_init(lqueue);
}

amxc_lqueue_is_empty()

AMXC_INLINE bool amxc_lqueue_is_empty

(

const amxc_lqueue_t *const

lqueue

)

Checks that the linked queue is empty.

Parameters

lqueue

a pointer to the linked queue structure

Returns

returns true when the linked queue contains no items, false when there is at least one item on the queue.

Definition at line 259 of file amxc_lqueue.h.

                                                             {
    return amxc_llist_is_empty(lqueue);
}

amxc_lqueue_it_init()

AMXC_INLINE int amxc_lqueue_it_init

(

amxc_lqueue_it_t *const

it

)

Initializes a linked queue iterator.

Initializes the linked queue iterator structure. All pointers are reset to NULL.

Note

When calling this function on an already initialized linked queue iterator, the linked queue iterator is reset and the queue the iterator was in is corrupted. Use amxc_lqueue_remove to remove the iterator from the queue

Parameters

it	a pointer to the linked queue iterator structure.

Returns

0 on success. -1 if a NULL pointer is given.

Definition at line 283 of file amxc_lqueue.h.

                                                    {
    return amxc_llist_it_init(it);
}

amxc_lqueue_new()

AMXC_INLINE int amxc_lqueue_new

(

amxc_lqueue_t **

lqueue

)

Allocates a linked queue.

Allocates and initializes memory to store a linked queue. This function allocates memory from the heap, if a linked queue is on the stack, it can be initialized using the function amxc_lqueue_init

Note

The allocated memory must be freed when not used anymore, use amxc_lqueue_delete to free the memory

Parameters

lqueue

a pointer to the location where the pointer to the new linked queue can be stored

Returns

-1 if an error occured. 0 on success

Definition at line 122 of file amxc_lqueue.h.

                                            {
    return amxc_llist_new(lqueue);
}

amxc_lqueue_remove()

AMXC_INLINE amxc_lqueue_it_t* amxc_lqueue_remove

(

amxc_lqueue_t *const

lqueue

)

Removes the first added item from the queue.

Parameters

lqueue

a pointer to the linked queue structure

Returns

The iterator to the first added item or NULL if no more items on the queue

Definition at line 228 of file amxc_lqueue.h.

                                                                  {
    return amxc_llist_take_first(lqueue);
}

amxc_lqueue_size()

AMXC_INLINE size_t amxc_lqueue_size

(

const amxc_lqueue_t *const

lqueue

)

Calculates the size of the queue, expressed in number of items.

Parameters

lqueue

a pointer to the linked queue structure

Returns

The number of items on the linked queue.

Definition at line 243 of file amxc_lqueue.h.

                                                           {
    return amxc_llist_size(lqueue);
}