Aztec® Programming Language
Version 1.1 Alpha 2

Copyright © 2010-2017, Aztec Development Group, All Rights Reserved

Download Aztec

Search        Contact Us

You keep carrying that anger...

It'll eat you up inside.

- Don Henley, J.D. Souther, Mike Campbell

 

aztec.util.ObjectQueue

public class ObjectQueue from<Collection>

Base

Collection

ObjectQueue

aztec.util.IObjectQueue

public class abstract IObjectQueue from<Base>

Base

IObjectQueue

The ObjectQueue class provides a general purpose dynamic queue class which can hold any type of object. The queue "mode" can be specified as "FIFO" (default) or "LIFO". It is derived from Collection, so satisfies all the requirements that entails.

 

The ObjectQueue class also supports an event handler to get control when an item is added to the list. This is useful for "server based" threads which respond to incoming object requests. The server thread registers an event handler with the queue and sits in a "waiting for events" mode. When another thread adds an item to the queue, the server thread wakes up and calls the QueueReceiveEvent event handler to process the incoming request.

 

The IObjectQueue class is an abstract interface class which contains a virtual event handler method for each event which the ObjectQueue class supports (currently just one - QueueReceiveEvent)

 

This ObjectQueue class accepts any type of class by storing the items as "Base" class entries. This means that when an item is retrieved from the queue, it typically needs to be changed to the class in question using the "as" keyword. The Aztec Class Framework also provides a rich set of "template" classes for lists and queues intended to address this usability problem.

 

ObjectQueue Methods

ObjectQueue() Constructor for the ObjectQueue class
Size() Returns number of items in the queue
AddItem() Adds an item to the end of the list (FIFO) or start of the list (LIFO) and trigger a receive event
AddExpressItem() Inserts an item at the beginning of the queue and trigger a receive event
GetItem() Gets next item from the queue and removes it
PeekItem() Gets next item from the queue without removing it
PeekItem() Gets item from the queue at specified one based position without removing it
GotoTop() Moves internal "pointer" to top of list
GotoBottom() Moves internal "pointer" to bottom of list
GetCurrentItem() Gets "current" object in collection and move pointer position
IsCurrentValid() Returns true if the "pointer" currently points at a valid position
Clear() Clears all items from the queue
QueueType() Returns the queue type as QueueType.LIFO or QueueType.FIFO
AddQueueReceiveHandler() Adds event handler for a "receive" event (AddItem(), AddExpressItem()) using a method reference
AddQueueReceiveHandler() Adds event handler for a "receive" event (AddItem(), AddExpressItem()) using an IQueue reference
OnQueueReceive() Event handler for QueueReceiveEvent processing

ObjectQueue Constants

Constant Data Item Data Type Value
ObjectQueue.FIFO int 1
ObjectQueue.LIFO int 2

IObjectQueue Methods

OnQueueReceive() Virtual method to handle QueueReceiveEvent processing

Derived Classes

See Also

 


ObjectQueue()

public method ObjectQueue(QueueType Mode = QueueType.FIFO, bool ProcessEvents = false)

Parameters

Mode

Queue type enumeration value (FIFO or LIFO)

ProcessEvents

Add event handling if true

Return Value

None

Description

Constructor for the ObjectQueue class. The queue mode is specified using one of the two QueueType enumeration values (FIFO - First In First Out, LIFO - Last In First Out) and the "process events" flag can also be specified. If true, the system sets up the default handler for queue receive events (OnQueueReceive()). If false, the event handling is not turned on.

 

ObjectQueue Class


Size()

public virtual method<int> Size()

Parameters

None

Return Value

Returns size of queue

Description

This method returns the total number of objects currently stored in the queue.

 

ObjectQueue Class


AddItem()

public method AddItem(Base Object)

Parameters

Object

Reference to object to be added to queue

Return Value

None

Description

This method adds the specified object reference to the queue. If it's a FIFO queue, the object is added to the end of the queue. If LIFO, it's added to the beginning of the queue. The storage for the queue is handled internally, and automatically grows the queue if necessary. The user of the class doesn't need to worry about any of the details.

 

This method will result in a QueueReceiveEvent if the queue was created with event processing turned on.

 

ObjectQueue Class


AddExpressItem()

public method AddExpressItem(Base Object)

Parameters

Object

Reference to object to be added to queue

Return Value

None

Description

This method adds the specified object reference to the queue. Regardless of queue type, this item is placed at the beginning of the queue so that the next "GetItem()" call will return this object.

 

This method will result in a QueueReceiveEvent if the queue was created with event processing turned on.

 

ObjectQueue Class


GetItem()

public method<Base> GetItem()

Parameters

None

Return Value

Object reference in first position

Description

This method returns the next object reference in the queue and removes the item from the queue. If the queue is empty, it returns null.

 

ObjectQueue Class


PeekItem()

public method<Base> PeekItem()

Parameters

None

Return Value

Object reference in first position

Description

This method returns the next object reference in the queue and does NOT remove the item from the queue. If the queue is empty, it returns null.

 

ObjectQueue Class


PeekItem()

public method<Base> PeekItem(int Position)

Parameters

Position

One based position

Return Value

Object reference at specified position

Description

This method returns the object reference at the specified one based position in the queue. If the position is not valid (less than one or greater than the current size of the queue), or if the queue is empty, a value of null is returned.

 

ObjectQueue Class


GotoTop()

public virtual method GotoTop()

Parameters

None

Return Value

None

Description

This method moves the internal "pointer" to the top of the list. This will always point at the queue position that corresponds to that position which would be returned using the next GetItem() method call. For FIFO, it will be the first item entered. For LIFO, it will be the last item entered.

 

The "GetCurrentItem()" method returns the object which is at the current pointer location.

 

ObjectQueue Class


GotoBottom()

public virtual method GotoBottom()

Parameters

None

Return Value

None

Description

This method moves the internal "pointer" to the bottom of the list. This will always point at the queue position that is at the opposite end of the queue from the position which would be returned using the next GetItem() method call. For FIFO, it will be the last item entered. For LIFO, it will be the first item entered.

 

The "GetCurrentItem()" method returns the object which is at the current pointer location.

 

ObjectQueue Class


GetCurrentItem()

public virtual method<Base> GetCurrentItem(bool Forward = true)

Parameters

None

Return Value

Reference to current item

Description

This method returns a reference to the object at the current "pointer" location within the list.

 

If the Forward flag is true, the current pointer location is then advanced to the next object in the list. If currently at the last position, the pointer is advanced to a "null" position.

 

If the forward flag is false, the current pointer is moved to the previous object in the list. If currently at the first position, the pointer is advanced to the "null" position.

 

If the pointer ends up at the "null" position, the next "GetCurrentItem()" call will return null. The "GotoTop()" or "GotoBottom()" method must be used to reset the pointer to a valid position.

 

If the collection is empty, this method also returns null.

 

ObjectQueue Class


IsCurrentValid()

public virtual method<bool> IsCurrentValid()

Parameters

None

Return Value

True if current position is valid

Description

Virtual method to return true if the "current" pointer within the queue points at a valid position, and returns false if not. If the queue is empty, or if the end of the queue has been surpassed by making a "GetCurrentItem()" call at the end of the queue, the current "pointer" does not point at a valid position (and GetCurrentItem() returns null), so this method returns false.

 

ObjectQueue Class


Clear()

public virtual method Clear()

Parameters

None

Return Value

None

Description

This method clears all items from the queue.

 

ObjectQueue Class


QueueType()

public method<QueueType> QueueType()

Parameters

None

Return Value

QueueType.LIFO or QueueType.FIFO

Description

This method returns the queue type enumeration value (FIFO or LIFO). This setting specifies how the data is retrieved from the queue.

 

ObjectQueue Class


AddQueueReceiveHandler()

public method AddQueueReceiveHandler(QueueReceiveHandler Handler, Base ExtraObject = null)

Parameters

Handler

Method reference to be executed when the event occurs

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers a method reference to be executed when an item is added to the queue (if "process events" is turned on for the queue). The 'AddItem()' and 'AddExpressItem()' methods both issue this event. An optional object can also be registered which will be sent to each event handler as it is executed.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an item added to queue in one thread can be handled by event handlers executing in one or more other threads.

 

The QueueReceiveHandler data type represents a method reference specific to a handler for QueueReceiveEvent. QueueReceiveHandler is defined as follows:

 

        public type<method<QeueReceiveEvent,Base>> QueueReceiveHandler

 

Given this definition, the method handler must be defined with the following signature (name can be anything):

 

        public method QueueReceiveMethod(QueueReceiveEvent event, Base Extra) { }.

 

ObjectQueue Class


AddQueueReceiveHandler()

public method AddQueueReceiveHandler(IObjectQueue Interface, Base ExtraObject = null)

Parameters

Interface

Reference to an IObjectQueue object

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers an IObjectQueue interface object to be executed when an item is added to the queue (if "process events" is turned on for the queue). The 'AddItem()' and 'AddExpressItem()' methods both issue this event. An optional object can also be registered which will be sent to each event handler as it is executed.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an item added to queue in one thread can be handled by event handlers executing in one or more other threads.

 

When an item is added to the queue, the OnQueueReceive() method within the IObjectQueue object will be executed.

 

ObjectQueue Class


OnQueueReceive()

public method virtual OnQueueReceive(QueueReceiveEvent QueueEvent, Base ExtraObject)

Parameters

QueueEvent

QueueReceiveEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This method is the default event handler for QueueReceiveEvent within the thread. It is invoked internally as a result of an item being added to the thread (if the ObjectQueue was created with the "process events" flag turned on). The 'AddItem()' and 'AddExpressItem()' methods both issue this event.

 

This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the ObjectQueue.AddQueueReceiveHandler() method register the event handlers which get invoked by this method.

 

If this method is overridden by a class derived from ObjectQueue, it must call this implementation of the method if it needs to execute handlers registered with the ObjectQueue.AddQueueReceiveHandler() methods.

 

ObjectQueue Class


OnQueueReceive()

public method virtual OnQueueReceive(QueueReceiveEvent QueueEvent, Base ExtraObject)

Parameters

QueueEvent

QueueReceiveEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This virtual method is the event handler for QueueReceiveEvent within the IObjectQueue interface class. The method which overrides it is invoked when an item is added to the queue and the interface object is registered with the ObjectQueue.AddQueueReceiveHandler() method.

 

IObjectQueue Class

 

Copyright © 2010-2017

Aztec Development Group

All Rights Reserved

Download Aztec