Home > Class Reference > ENSLIB namespace > %SYSTEM.IPQ


InterProcessQueues are for first in first out message transport.
One job creates it, then another job opens it. The creator defines if it's going to put or get messages into the queue and also specifies the queue size.
To use this service, you must create a subcls derived from this class. It is required to cache the queue state. When done with the queue, invoke the Delete() method to cleanup. The shared queue will disapear when both ends cleanup.
The Put() method inserts a message in the queue, and GetAny() delivers the received message to the subclass' MsgReceived method.
If the queued message is larger than the available space, Put() will wait for the getter to dequeue messages. Put doesn't timeout, it waits forever for the messages to be dequeued. If the getter doesn't pickup the queued messages, Put() will wait for the queue to drain.
It can deadlock if multiple jobs doing "Get" and "Put" depend on each other!!
If the queued messages are larger than the allocated queue size, the getter will build the received message on the stack, and when the whole message is received then it will invoke the MsgReceived() method.
To avoid Put from waiting indefinitely, GetState() could be used to find out if the getter is receiving messages and has available space.

Method Inventory


classmethod Attach(name As %String) as IPQ [ Language = objectscript ]
Given a queue name return an oref attached to this preexisting queue
method Create(name As %Binary, InitialSize As %Integer, type As %Integer) as %Integer [ Language = cpp ]
Create and init the InterProcessQueue (IPQ). It must be called before accessing any of its methods.
Create will try to pre allocate the specified number of 32K chunks for the message queue
Create will fail if another queue with the same name already exists.
Returns zero on failure else returns the number of allocated chunks
If IPQ type is 0 (default) the creator is going to use it for for getting messages, else if it's 1 it's going to use it for putting messages.
Note: After Creating or Opening an IPQ object for getting, you must Delete() your object before dropping the object/oref. Otherwise IPQ will keep a refcount on the oref which may not be dereferenced and it will linger forever.
method Delete() as %Integer [ Language = cpp ]
InterProcessQueues are a shared object and they don't go away until they are deleted explicitly. After deletion any references to this object from the current job or any other job will fail.
classmethod GetAny(timeout As %Integer) as %Integer [ Language = cpp ]
Waits the specified amount of time to get any data from any of the Created InterProcessQueues.
When any data is queued it delivers the rcvd data to the MsgReceived() method..
Returns the number of delivered messages, or -1 if there are no objects in the wait list.
it will wait for the specified timeout in seconds. If timeout is zero just polls, and if timeout is -1 waits forever. Return zero on timeout.
Note: It invokes the MsgReceived() method in a round robin order.
method GetState() as %String [ Language = cpp ]

Returns the state of the IPQ object.
0 if the node is not connected otherwise 1^Total allocated space^Available free space^

method GetStats() as %String [ Language = cpp ]

Returns the collected stats.
Num Messages^Num times Put waited^Num contiguous messages^Num chars queued^An Internal counter^

method MsgReceived(value As %String) [ Language = cpp ]
Method is invoked by the GetAny() class method when the InterProcessQueue has data for this queue. Note: this class is an abstract class and the derived sub-class must overwrite this method before it can be used.
method Open(name As %Binary) as %Integer [ Language = cpp ]
Init this object with the pre existing queue. It must be called before accessing any of its methods.
Returns zero on failure.
Note: it must be created by some other job before openning.
The opener can only put or get depending on how it's created.
method Put(data As %String) as %Integer [ Language = cpp ]

Puts the passed data in the queue. If any errors, it return zero, otherwise it returns the number of chars queued.
If the queue is full (basically the creator is not getting), it will wait until space is available.
Note: Put can take multiple params, and they will be queued in left to right order.