|
|
||
|
In Python the outgoing message is created by the agent when the user code asks it for sending a new message:
message = my_agent.send("tcp://somewhere:12345",
"my_object", "do_something", content)
The parameters object provided for the message is no longer referenced for this particular message and can be therefore modified (or destroyed) by the user code without affecting the message in any way.
Above, the message is sent to the given target, destination object name and with a given message name.
The content object is supposed to be a parameters or a dictionary object; an empty dictionary is used by default.
The possible message states are defined by constants within the OutgoingMessage class.
As described in the main part of this section, message states can be tracked and used for synchronization to enable the user code to align its processing with the message progress that is performed by background tasks.
Thus, a complete idiom for message sending in Python can involve the following structure:
try:
message =
my_agent.send("tcp://somewhere:12345",
"my_object", "do_something", content)
# do something else while the message makes progress
# or synchronize with its completion:
message.wait_for_completion()
state = message.get_state()[0]
if state == OutgoingMessage.REPLIED:
reply_content = message.get_reply()
# extract values from the reply content and use them
...
elif state == OutgoingMessage.REJECTED:
reason = message.get_exception_msg()
# the reason is a description of the exception or error
# that caused the message rejection
...
else:
# the message has been abandoned,
# because the given channel has been closed
...
message.close()
except YAMIError as ex:
# message could not be sent because the connection
# was not established with remote agent
...
In addition to the proper idiom for managing complete messaging cycle in the command-response interaction, the above example shows that in case of successful reception of message reply, the reply content can be extracted from the outgoing message object.
The wait_for_completion() and wait_for_transmission() functions support the optional relative timeout argument. If the timeout argument is omitted, the execution can potentially block forever. Absolute timeouts are not supported by the Python library.
Outgoing messages are associated with some internal resources in the agent.
These resources should be disposed when no longer needed, which is achieved with the close() method call. Alternatively, outgoing messages can be used within the context manager, which automates their cleanup.