[ Main Table Of Contents | Table Of Contents | Keyword Index ]

c::queue(n) 1 doc "Tcl Data Structures"

Name

c::queue - Create and manipulate C-level queue objects

Table Of Contents

Synopsis

Description

Welcome to Struct, a set of packages providing various data structures to Tcl, and additional operations for existing Tcl structures.

This package provides a basic C API for the creation and use of queues. It does provide neither Tcl commands nor other items visible at script level.

The package is meant to be used by other C level data structure packages, either internally, or providing a Tcl level API to it. An example of the latter is the C implementation of package struct::queue.

To support this the package provides its C API by means of a stubs table which can be imported.

API

CQUEUE cqueue_create ( CQUEUE_CELL_FREE fun, void* clientdata )

This function creates and initializes a new queue object and returns its handle. The client-data is simply stored and available upon request, see function cqueue_clientdata_get below.

The free function fun is for the release of memory associated with the cells of the new queue. It may be NULL.

void cqueue_destroy ( CQUEUE q )

This function destroys the specified queue object, releasing all allocated memory.

The cell release function is called for all cells left in the queue.

long int cqueue_size ( CQUEUE q )

This function returns the number of cells in the queue.

void cqueue_first ( CQUEUE q )

This function returns the first cell in the queue.

The code asserts that the queue is not empty.

void cqueue_last ( CQUEUE q )

This function returns the last cell in the queue.

The code asserts that the queue is not empty.

CSLICE cqueue_head ( CQUEUE q, long int n )

This function returns the first n cells in the queue as a slice, with the first cell of the queue as the first element of the slice (natural internal order).

CSLICE cqueue_tail ( CQUEUE q, long int n )

This function returns the last n cells in the queue as a slice, with the last cell of the queue as the last element of the slice (natural internal order).

CSLICE cqueue_get ( CQUEUE q, long int at, long int n )

This function returns the n cells starting at index at in the queue as a slice, with the first cell in the queue as the first element of the slice (natural internal order).

The indexing uses the natural internal order:

Index 0 addresses the first cell, whereas

index 'cqueue_size()-1' addresses the last cell.

void cqueue_append ( CQUEUE q, void* item )

This function adds the item to the queue, at the end.

void cqueue_prepend ( CQUEUE q, void* item )

This function adds the item to the queue, at the head.

void cqueue_append_slice ( CQUEUE q, CSLICE sl )

This function adds all items in the slice to the queue, at the end, in slice order (keeping their order in the queue). It is a convenience function reducing the number of calls to cqueue_append for bulk operations.

void cqueue_prepend_slice ( CQUEUE q, CSLICE sl )

This function adds all items in the slice to the queue, at the head, in slice order (reversing their order in the queue). It is a convenience function reducing the number of calls to cqueue_prepend for bulk operations.

void cqueue_remove_head ( CQUEUE q, long int n )

This function removes the first n cells from the queue.

The cell release function is called for all removed cells. This is in contrast to function cqueue_drop_head below.

void cqueue_remove_tail ( CQUEUE q, long int n )

This function removes the last n cells from the queue.

The cell release function is called for all removed cells. This is in contrast to function cqueue_drop_tail below.

void cqueue_clear ( CQUEUE q )

This convenience function is a variant cqueue_remove_head which removes all cells from the queue. After the operation q is empty.

void cqueue_drop_head ( CQUEUE q, long int n )

This function drops the first n cells from the queue.

Note: The cell release function is not called for the removed cells. This is in contrast to function cqueue_remove_head above.

void cqueue_drop_tail ( CQUEUE q, long int n )

This function drops the last n cells from the queue.

Note: The cell release function is not called for the removed cells. This is in contrast to function cqueue_remove_tail above.

void cqueue_drop_all ( CQUEUE q )

This convenience function is a variant of cqueue_drop_head which drops all cells from the queue. After the operation q is empty.

void cqueue_move ( CQUEUE q, CQUEUE src, long int n )

This function moves the first n cells in the queue src to the queue q, adding them at the end. This keeps their order. As the cells are not destroyed the release function is not called.

As a basic precaution the release functions of both queues are compared, and have to match. The code will assert this and panic if the condition is not true.

void cqueue_move_all ( CQUEUE q, CQUEUE src )

This convenience function is a variant of cqueue_move which moves all cells of the source to the destination. After the operation src is empty.

void cqueue_clientdata_set ( CQUEUE q, void* clientdata )

This function sets new client data into the queue.

void* cqueue_clientdata_get ( CQUEUE q )

This function returns the client data currently stored in the queue.

License

This package, written by Andreas Kupries, is BSD licensed.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Struct Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.

Keywords

data structures, lifo, queue

Category

Data structures