mxQueue - A Queue Implementation for Python

Interface

Queue Constructors

There are two ways to construct a Queue from scratch:

Queue([initial_size])

Returns a new empty Queue instance allocating at least the given number of slots for queue elements. If the parameter is not given a reasonable default is chosen.

QueueFromSequence(seq)

Constructs a Queue instance from the given sequence. The instance is filled with all the elements found in the sequence by pushing the items from index 0 to len(seq)-1 in that order, i.e. popping all elements from the Queue results in a reversed sequence.

Instance Methods

A Queue instance has the following methods:

push(x)

Pushes the object x onto the queue.

push_many(sequences)

Pushes the objects in sequence from left to right onto the queue. If errors occur during this process, the already pushed elements are discarded from the queue and it returns to its original state.

pop()

Pops the top element off of the queue.

pop_many(n)

Pops the top n elements and returns them in form of a tuple. If less than n elements are on the queue, the tuple will contain all queue entries and the queue will then be empty again. The order is top to bottom, i.e. s.pop_many(2) == (s.pop(),s.pop())

as_tuple()

Returns the queue's content as tuple, without modifying it.

as_list()

Returns the queue's content as list, without modifying it.

clear()

Clears the queue.

resize([size=len(queue)])

Resize the queue buffer to hold at least size entries.

You can call this method without argument to force the queue to shrink its memory buffer to the minimal limit needed to hold the contained elements.

Note that no method for testing emtpyness is provided. Use len() for that or simply test for trueness, e.g. while s: print s.pop() will loop as long as there are elements left on the Queue s. This is much faster than going through the method calling process -- even when the method being called is written in C.

Examples of Use

Well, there's not much to show:

from mx.Queue import *
s = Queue()
for i in range(1000):
    s.push(i)
while s:
    print s.pop()
# which could also be done as:
s = QueueFromSequence(range(1000))
while s:
    print s.pop()
# or a little different
s = QueueFromSequence(range(1000))
print s.as_tuple()
print s.as_list()
	

Supported Data Types in the C-API

Please have look at the file mxQueue.h for details. Basically all of the above Python interfaces are also available in the C API.

To access the module, do the following (note the similarities with Python's way of accessing functions from a module):

#include "mxQueue.h"

...
    PyObject *v;

    /* Import the mxQueue module */
    if (mxQueue_ImportModuleAndAPI())
	goto onError;

    /* Access functions from the exported C API through mxQueue */
    v = mxQueue.Queue(0);
    if (!v)
	goto onError;

    /* Type checking */
    if (mxQueue_Check(v))
        printf("Works.\n");

    Py_DECREF(v);
...
	

Package Structure

[Queue]
	mxQueue
	

Entries enclosed in brackets are packages (i.e. they are directories that include a __init__.py file). Ones without brackets are just simple subdirectories that are not accessible via import. These are used for compiling the C extension modules which will get installed in the same place where all your other site specific extensions live (e.g. /usr/local/lib/python-x.xx/site-packages).

The package Queue imports all symbols from the extension mxQueue, so import Queue; s = Queue.Queue() gives you a Queue instance in s.

Support

Copyright & License

History & Future

There were no significant changes between 2.0.2 and 2.0.3.

Changes from version 2.0.0 to 2.0.2:

• Fixed a bug in the coercion code which surfaced due to the rich comparison changes in Python 2.1. Python 2.1 will now compare Queue objects to other objects without raising a TypeError.

Version 2.0.0 was the initial public version.