%SYSTEM.IPQ
hidden class %SYSTEM.IPQ extends %Library.SystemBase
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
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.
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.
Returns the state of the IPQ object.
0 if the node is not connected otherwise 1^Total allocated space^Available
free space^
Returns the collected stats.
Num Messages^Num times Put waited^Num contiguous messages^Num chars queued^An Internal counter^
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.
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.