John Bowe, bowe@osf.org
15-September-1996
This document is organized into sections on Data Structures, Operations At a Glance, and Some Implementation Details.
For convenience matching IDL files are available
Also included are data structures that may be written to a backing store. An IDL file is used to generate the encoding and decoding functions.
Structures used internally by the q-mgr need not be defined here and may differ, depending on implementation. Internally-used structures will probably be defined for efficiency of the q-mgr, not elegance of external interface.
The names of attributes and operations here are not necessarily those of the actual IDL file.
There will be some "support" structured defined for the RPCs,
such as lists of some of the structures defined below.
(A "list" is simply a count (unsigned32)
and an array of the structure of interest,
[ptr,size_is(count)] my_struct_t *list;
.)
These need no be defined in this document,
though they will be defined in the IDL file.
Attribute | Type | Description |
---|---|---|
id | uuid_t | UUID of this queue |
name | string | name of the queue - either simple string (for queue name under "junction") or full CDS name for where to try to export. |
annotation | string | uninterpreted annotation string |
aliases | array of strings | alternate names of this queue |
len | unsigned32 | number of items currently available in queue |
max_len | unsigned32 | max items allowed in queue |
flags | unsigned32 | various bit flags (persistence, etc.) |
empty_timeout | utc_t | time of "empty inactivity" before deleting queue |
last_activity | utc_t | time of last activity |
create_time | utc_t | time of queue creation |
Attribute | Type | Description |
---|---|---|
id | string | UUID of this item in the queue (this is also used as a key for storing the items to a backing store) |
datatype | uuid_t | semantically identifies the message, and allows recipient to determine how do decode the message |
msgtype | enum (data, ack, etc.) | data, ack, etc. |
notice | unsigned32 | bitmask of options for notices to send (upon dequeue, expiration, exception, none) |
sender | sec_id_pa_t | PAC of the principal who sent the message |
persistence | enum | persistence behavior |
flags | unsigned32 | various bit flags (protection, etc.) |
priority | unsigned32 | priority of the item |
time_enqueued | utc_t | when message was enqueued by q-mgr |
expire_time | utc_t | when this message will expire |
valid_time | utc_t | when this message will be available for dequeue |
reply_queue | string | name of queue for replies |
A structure is defined for the mask used to specify selection criteria. A mask is a typed-structure with a triplet of: datatype (int, uuid_t, utc_t, string), relation (equal, less than, etc.), and a value. Selection is based on an array of these masks.
byte
)
and the length of the array.
Operation | Description | Parameters |
---|---|---|
mos_mgmt_create_queue | create a new queue | In: name, queue attributes, flags
Out: UUID of new queue |
mos_mgmt_get_id_list | get list of queues IDs | In: -
Out: array of queue UUIDs |
mos_mgmt_get_name_list | get list of queues names | In: -
Out: array of queue names |
mos_mgmt_rename | rename a queue | In: old queue name, new queue name
Out: - |
mos_mgmt_move | migrate a queue from one q-mgr to another (this operation is performed on the destination q-mgr) (This needs more thought. Probably better for API to do the work.) | In: queue name (destination), queue name (source)
Out: - |
Operation | Description | Parameters |
---|---|---|
mos_q_enqueue | add an item to an existing queue | In: queue name, attributes, message
Out: UUID of item |
mos_q_dequeue | dequeue first item from a queue that matches given selection criteria; optionally blocks, depending on flags | In: queue name, selection filter, flags
Out: attributes, message |
mos_q_dequeue_next | dequeue first item on a queue | In: queue name
Out: attributes, message |
mos_q_peek | return copy of first item from a queue that matches given selection criteria; optionally blocks, depending on flags | In: queue name, selection filter, flags
Out: attributes, message |
mos_q_purge | purge/delete item in queue with given message ID optionally blocks, depending on flags | In: queue name, message ID
Out: attributes, message |
mos_q_retrieve_attr | retrieve attributes of next item from queue that matches given selection criteria | In: queue name, selection filter
Out: attributes |
mos_q_ping | determines if a given queue exists | In: queue name
Out: uuid |
mos_q_retrieve_attr_by_id | retrieve attributes of item from queue with given message ID | In: queue name, message ID
Out: attributes |
mos_q_ping | determines if a given queue exists | In: queue name
Out: queue ID |
mos_q_get_id_list | get list of message IDs | In: queue name
Out: array of message IDs |
mos_q_delete_queue | delete a queue | In: queue name, flags
Out: - |
mos_q_get_attr_by_name | get the attributes of a given queue | In: queue name
Out: attributes |
mos_q_get_attr_by_id | get the attributes of a given queue, based on ID | In: queue ID (UUID)
Out: attributes |
mos_q_set_attr_by_name | set the attributes of a given queue | In: queue name, attributes
Out: - |
mos_q_set_attr_by_id | set the attributes of a given queue, based on ID | In: queue ID (UUID), attributes
Out: - |
mos_q_move_item | move a single message from one queue to another, given message ID | In: queue names, message ID
Out: - |
There will be several backing stores: one for the ACL database, one for queue attributes, and one for queue items (messages) themselves. The latter is use only for messages specified as "persistent".
Queue attributes will be kept in memory. (They are not that large, and this information should be readily available for various reasons, such as testing timeouts and checking if name already exists.)
mos_mgmt_create_queue
mos_mgmt_get_id_list
mos_mgmt_rename
mos_mgmt_move
NOTE: This still needs some thought. The API can probably do all the work better, or at least more conveniently.
mos_q_enqueue
mos_q_dequeue
mos_q_dequeue_next
mos_q_dequeue
.
Dequeues next available message and attributes from a queue.
mos_q_peek
mos_q_dequeue
, but only a copy of the message
attributes and body are returned; it is not dequeued.
mos_q_purge
mos_q_retrieve_attr
mos_q_dequeue
, but a message body is not returned
and the message is not dequeued.
Steps:
mos_q_retrieve_attr_by_id
mos_q_dequeue
, but a message body is not returned
and the message is not dequeued.
Steps:
mos_q_ping
mos_q_retrieve_attr
,
but optimized for just determining if a queue is there.
It is indended for the API's "attach" call.
Steps:
mos_q_get_id_list
mos_q_delete_queue
mos_q_get_attr_by_name
and mos_q_get_attr_by_id
mos_q_set_attr_by_name
and mos_q_set_attr_by_id
mos_q_move_item
Steps: read queue-info backing store, populating in-memory list of queue information; read queue-data backing store, populating queue items (these are the persistent messages).
In production dced
will start the queue manager.
dced will maintain startup parameters, such as directory, principal, etc.
[ Detailed Design TOC | Messaging ]