set_message_tupleT_set_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple (Operator)

Name

set_message_tupleT_set_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple — Add a key/tuple pair to the message.

Signature

Description

set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple stores a tuple associated with a key in the message, which behaves as a dictionary-like data container. The message is denoted by the MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle parameter.

TupleDataTupleDataTupleDataTupleDataTupleDatatupleData including strings is copied by the operation, and can thus be immediately reused. An empty tuple is considered as a valid value that can be associated with the key. If any data (tuple or object) was already associated with given key (KeyKeyKeyKeyKeykey), the old data is destroyed by set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple and replaced by TupleDataTupleDataTupleDataTupleDataTupleDatatupleData.

The KeyKeyKeyKeyKeykey has to be a non-empty string consisting solely of lowercase or uppercase ASCII letters, digits and underscores, while only a letter can be at the first position of the key. The key string is treated case sensitive.

The tuple data for the given key can be retrieved again from the message using get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple.

Attention

Note that if the tuple contains any handles (which are treated as simple integers) only the handle values are copied by the operation, not the resources behind those handles.

Parallelization

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

This operator modifies the state of the following input parameter:

• MessageHandleMessageHandleMessageHandleMessageHandleMessageHandlemessageHandle

Parameters

Example (HDevelop)

create_message (Message)
set_message_tuple (Message, 'simple_integer', 27)
set_message_tuple (Message, 'simple_string', 'Hello world')
set_message_tuple (Message, 'mixed_tuple', ['The answer', 42])

Result

If the operation succeeds, set_message_tupleset_message_tupleSetMessageTupleset_message_tupleSetMessageTupleSetMessageTuple returns 2 (H_MSG_TRUE). Otherwise an exception is raised. Possible error conditions include invalid parameters (handle or key) or resource allocation error.

Possible Predecessors

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage

Possible Successors

enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage, set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj

Alternatives

set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj

See also

create_messagecreate_messageCreateMessagecreate_messageCreateMessageCreateMessage, clear_messageclear_messageClearMessageclear_messageClearMessageClearMessage, get_message_tupleget_message_tupleGetMessageTupleget_message_tupleGetMessageTupleGetMessageTuple, set_message_objset_message_objSetMessageObjset_message_objSetMessageObjSetMessageObj, get_message_objget_message_objGetMessageObjget_message_objGetMessageObjGetMessageObj, set_message_paramset_message_paramSetMessageParamset_message_paramSetMessageParamSetMessageParam, get_message_paramget_message_paramGetMessageParamget_message_paramGetMessageParamGetMessageParam, enqueue_messageenqueue_messageEnqueueMessageenqueue_messageEnqueueMessageEnqueueMessage, dequeue_messagedequeue_messageDequeueMessagedequeue_messageDequeueMessageDequeueMessage

Module

Foundation