Aztec® Programming Language
Version 1.1 Alpha 2

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

Download Aztec

Search        Contact Us

It's important to me...

That you know you are free.

'Cause I never want to make you change... for me.

- Todd Rundgren

 

aztec.util.PrimitiveRefQueue

public class PrimitiveRefQueue<T> from<Collection>

Base

Collection

PrimitiveRefQueue<>

aztec.util.IPrimitiveRefQueue

public class abstract IPrimitiveRefQueue<T> from<Base>

Base

IPrimitiveRefQueue<>

The PrimitiveRefQueue class is a "template" based class that takes a class name as an argument to indicate what type of primitive class reference is being stored in the queue. Once a specific instance of the PrimitiveRefQueue<> is created (simply by using It in code), the class provides a general purpose dynamic queue class which can only hold that particular type of primitive object reference. The queue "mode" can be specified as "FIFO" (default) or "LIFO". It is derived from Collection, so satisfies all the requirements that entails.

 

This class is intended for use with Aztec primitive classes (int, float, etc.) and it holds primitive object references. There are special template based queue classes for non-primitive classes and primitive object values, Queue<> and PrimitiveQueue<>.

 

The beauty of the template based PrimitiveRefQueue<> classes versus the ObjectQueue class is that the template based implementation is built so the the system takes only a particular type of data to store in the queue, and when an item is retrieved, the type of data is known by the compiler, so the caller gets a version of the "GetItem()" method specific to the data type being contained in the PrimitiveRefQueue<>, so no extra effort is required to change the return type to the desired type.

 

The PrimitiveRefQueue<> class also supports an event handler to get control when a primitive 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 PrimitiveRefQueueEvent<T> event handler to process the incoming request.

 

The IPrimitiveRefQueue<> class is an abstract interface class which contains a virtual event handler method for each event which the PrimitiveRefQueue<> class supports (currently just one - PrimitiveRefQueueEvent<>).

 

The template class is not usable by itself, and an implementation of the class must be created, using a valid Aztec primitive class, in order to use the PrimitiveRefQueue<> class. The creation of a single implementation of the PrimitiveRefQueue<> template class can occur anywhere in Aztec code where a class can be used.Once a specific implementation of the PrimitiveRefQueue<> class is created, a family of associated types is also created, all in support of this single implementation of the PrimitiveRefQueue<>. For example, the following data definition using the PrimitiveRefQueue<> class, with the string class as an argument to the class, will also result in the automatic creation of the other types as shown below.

 

        data<PrimitiveRefQueue<string>> MyStringRefQueue

 

        Results in the following data types also being created automatically by the Aztec system

 

        public class abstract IPrimitiveRefQueue<string>

        public class PrimitiveRefQueueEvent<string>

        type<method<PrimitiveRefQueueEvent<string>,Base>> PrimitiveRefQueueHandler<string>

 

Every unique implementation of the PrimitiveRefQueue<> class will have its own set of supporting class/types as described above.

 

Note that the description of the PrimitiveRefQueue<> and IPrimitiveRefQueue<> class below use "T" as the placeholder in the class definition. It will be used throughout the class as a method argument and a retun type. When a specific implementation of the PrimitiveRefQueue<> class is created, the "T" will be replaced with the class that was passed into the PrimitiveRefQueue<> class definition (such as the "string" example shown above).

PrimitiveRefQueue<> Methods

PrimitiveRefQueue() Constructor for the PrimitiveRefQueue<> 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 PrimitiveRefQueueEvent<> processing

IPrimitiveRefQueue Methods

OnQueueReceive() Virtual method to handle PrimitiveRefQueueEvent<> processing

Derived Classes

See Also

 


PrimitiveRefQueue()

public method PrimitiveRefQueue(int 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 PrimitiveRefQueue<> 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.

 

PrimitiveRefQueue<> Class


Size()

public virtual method<int> Size()

Parameters

None

Return Value

Returns size of queue

Description

This method returns the total number of primitive object references currently stored in the queue.

 

PrimitiveRefQueue<> Class


AddItem()

public method AddItem(T ref ObjectReference)

Parameters

ObjectReference

Primitive object reference to be added to queue

Return Value

None

Description

This method adds the specified primitive 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 PrimitiveRefQueueEvent<> if the queue was created with event processing turned on.

 

PrimitiveRefQueue<> Class


AddExpressItem()

public method AddExpressItem(T ref ObjectReference)

Parameters

ObjectReference

Primitive object reference to be added to queue

Return Value

None

Description

This method adds the specified primitive 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 reference.

 

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

 

PrimitiveRefQueue<> Class


GetItem()

public method<T ref> GetItem()

Parameters

None

Return Value

Primitive object reference in first position

Description

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

 

PrimitiveRefQueue<> Class


PeekItem()

public method<T ref> PeekItem()

Parameters

None

Return Value

Primitive object reference in first position

Description

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

 

PrimitiveRefQueue<> Class


PeekItem()

public method<T ref> PeekItem(int Position)

Parameters

Position

One based position

Return Value

Primitive object reference at specified position

Description

This method returns the primitive 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, it returns null.

 

PrimitiveRefQueue<> 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.

 

PrimitiveRefQueue<> 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.

 

PrimitiveRefQueue<> Class


GetCurrentItem()

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

Parameters

None

Return Value

Reference to current item

Description

This method returns a reference to the primitive object reference 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 returns null.

 

PrimitiveRefQueue<> 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.

 

PrimitiveRefQueue<> Class


Clear()

public virtual method Clear()

Parameters

None

Return Value

None

Description

This method clears all items from the queue.

 

PrimitiveRefQueue<> 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.

 

PrimitiveRefQueue<> Class


AddQueueReceiveHandler()

public method AddQueueReceiveHandler(PrimitiveRefQueueHandler<T> 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 PrimitiveRefQueueHandler<T> data type represents a method reference specific to a handler for PrimitiveRefQueueEvent<T>. PrimitiveRefQueueHandler<T> is defined as follows:

 

        public type<method<PrimitiveRefQeueEvent<T>,Base>> PrimitiveRefQueueHandler<T>

 

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

 

        public method QueueReceiveMethod(PrimitiveRefQueueEvent<T> event, Base Extra) { }.

 

PrimitiveRefQueue<> Class


AddQueueReceiveHandler()

public method AddQueueReceiveHandler(IPrimitiveRefQueue<T> Interface, Base ExtraObject = null)

Parameters

Interface

Reference to an IPrimitiveRefQueue<> 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 IPrimitiveRefQueue<> 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 IPrimitiveRefQueue<> object will be executed.

 

PrimitiveRefQueue<> Class


OnQueueReceive()

public method virtual OnQueueReceive(PrimitiveRefQueueEvent<T> QueueEvent, Base ExtraObject)

Parameters

QueueEvent

PrimitiveRefQueueEvent<> 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 PrimitiveRefQueueEvent<> within the thread. It is invoked internally as a result of an item being added to the thread (if the PrimitiveRefQueue<> 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 PrimitiveRefQueue<T>.AddQueueReceiveHandler() method register the event handlers which get invoked by this method.

 

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

 

PrimitiveRefQueue<> Class


OnQueueReceive()

public method virtual OnQueueReceive(PrimitiveRefQueueEvent<T> QueueEvent, Base ExtraObject)

Parameters

QueueEvent

PrimitiveRefQueueEvent<> 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 PrimitiveRefQueueEvent<> within the IPrimitiveRefQueue<> 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 IPrimitiveRefQueue<>.AddQueueReceiveHandler() method.

 

IPrimitiveRefQueue<> Class

 

Copyright © 2010-2017

Aztec Development Group

All Rights Reserved

Download Aztec