set_message_queue_param — Set message queue parameters or invoke commands on the queue.
set_message_queue_param( : : QueueHandle, GenParamName, GenParamValue : )
set_message_queue_param sets message
queue parameters or invokes action commands on the queue.
Multiple parameters and action commands can be passed through a single
set_message_queue_param call, passing multiple parameter names
in a tuple GenParamName and corresponding values
in GenParamValue. There must be always the same number
of names and values and the values must be in the same order
as the names. The parameters and action commands are applied
in the same order passed in GenParamName. It is important to
understand that in particular in case of the action commands, it might not
be possible to revert the effect of previous action commands if a later
command fails, the caller therefore might need to be careful when
setting multiple commands in a single call.
Currently supported parameter names are:
Aborts any dequeue_message operator waiting in any thread
for data to be delivered. Any currently waiting call will unblock
and return H_ERR_MQCNCL. Any dequeue_message call invoked
in the future will return H_ERR_MQCNCL immediately regardless of the
queue status.
This command is typically needed for cleanup when any threads
using the message queue and possibly blocked in dequeue_message
must be released, because it is not allowed to destroy the queue
(clear_message_queue) while any operators might still use it.
It might be necessary to wait for the completion of those threads
after invoking the 'abort_dequeuing' command to be sure
any operators using the queue are completed.
The message data currently stored in the message queue is not affected by the command. The effect of canceling any further 'abort_dequeuing' calls can be reset again using the 'restore_queue' command.
The parameter value must be integer 1.
Clears the effect of a previous 'abort_dequeuing' command.
This means the next call to dequeue_message will again
attempt to deliver message data.
The parameter value must be integer 1.
Flushes the queue. All currently enqueued messages are removed from the queue and all associated resources, in particular the tuple or object data stored in the messages, are released.
The parameter value must be integer 1.
Sets the maximum number of messages that can be stored in the queue.
The enqueue_message operator call would fail (H_ERR_MQOVL)
if the queue would contain more messages after the operation than
the defined maximum.
Setting the 'max_message_num' parameter has no effect on the messages already present in the queue. No messages that are already in the queue can be removed by this operation.
The parameter value can be a positive integer or -1 if the queue size should be unlimited. The string value 'infinite' is accepted as well. The queue size is unlimited by default.
QueueHandle (input_control) message_queue → (handle)
Message queue handle.
Number of elements: QueueHandle == 1
Restriction: QueueHandle != 0
GenParamName (input_control) string(-array) → (string)
Names of the queue parameters or action commands.
Number of elements: GenParamName == GenParamValue
Default value: 'max_message_num'
List of values: 'abort_dequeuing', 'flush_queue', 'max_message_num', 'restore_queue'
GenParamValue (input_control) tuple(-array) → (string / integer / real)
Values of the queue parameters or action commands.
Number of elements: GenParamName == GenParamValue
Default value: 1
Suggested values: 1, -1
* abort waiting dequeue_message operators set_message_queue_param (Queue, 'abort_dequeuing', 1)
If all the operator parameters and their values are valid,
set_message_queue_param returns 2 (H_MSG_TRUE). Otherwise an exception is
raised.
create_message_queue,
clear_message_queue,
enqueue_message,
dequeue_message,
get_message_queue_param,
create_message,
clear_message,
set_message_tuple,
get_message_tuple,
set_message_obj,
get_message_obj
Foundation