upstage.communications package#

Submodules#

upstage.communications.comms module#

Comms message and commander classes.

class CommsManager(*, name: str, mode: str | None = None, init_entities: list[tuple[Actor, str]] | None = None, send_time: float = 0.0, retry_max_time: float = 1.0, retry_rate: float = 0.166667, debug_logging: bool = False)#

Bases: UpstageBase

A class to manage point to point transfer of communications.

Works through simpy.Store or similar interfaces. Allows for degraded comms and comms retry.

If an Actor contains a CommunicationStore, this object will detect that and use it as a destination. In that case, you also do not need to connect the actor to this object.

Example

>>> class Talker(UP.Actor):
>>>     comms = UP.ResourceState[SIM.Store](default=SIM.Store)
>>>
>>> talker1 = Talker(name='MacReady')
>>> talker2 = Talker(name='Childs')
>>>
>>> comm_station = UP.CommsManager(name="Outpost 31", mode="voice")
>>> comm_station.connect(talker1, talker1.comms)
>>> comm_station.connect(talker2, talker2.comms)
>>>
>>> comm_station.run()
>>>
>>> # Typically, do this inside a task or somewhere else
>>> putter = comm_station.make_put(
>>>     message="Grab your flamethrower!",
>>>     source=talker1,
>>>     destination=talker2,
>>>     rehearsal_time_to_complete=0.0,
>>> )
>>> yield putter
...
>>> env.run()
>>> talker2.comms.items
    [Message(sender=Talker: MacReady, message='Grab your flamethrower!',
    destination=Talker: Childs)]

static clean_message(message: str | Message) → MessageContent#

Test to see if an object is a message.

If it is, return the message contents only. Otherwise return the message.

Parameters:: message (str | Message) – The message to clean
Returns:: The message as a message content object.
Return type:: MessageContent

connect(entity: Actor, comms_store_name: str) → None#

Connect an actor and its comms store to this comms manager.

Parameters:

entity (Actor) – The actor that will send/receive.
comms_store_name (str) – The store state name for receiving

make_put(message: str | Message | MessageContent | dict, source: Actor, destination: Actor, rehearsal_time_to_complete: float = 0.0) → Put#

Create a Put request for a message into the CommsManager.

Parameters:

source – The message sender
destination – The message receiver, who must be connected to the CommsManager
message – Arbitrary data to send
rehearsal_time_to_complete (float, optional) – Planning time to complete the event (see Put), by default 0.0
Returns
-------
Put – UPSTAGE Put event object to yield from a task

run() → Generator[Event, Any, None]#

Run the communications message passing.

Yields:: Generator[SimpyEvent, Any, None] – Simpy Process

store_from_actor(actor: Actor) → Store#

Retrieve a communications store from an actor.

Parameters:: actor (Actor) – The actor
Returns:: A Comms store.
Return type:: Store

test_if_link_is_blocked(message: Message) → bool#

Test if a link is blocked.

Parameters:: message (Message) – Message with sender/destination data.
Returns:: If the link is blocked.
Return type:: bool

class Message(sender: Actor, content: MessageContent, destination: Actor, header: str | None = None, time_sent: float | None = None, time_received: float | None = None)#

Bases: object

A message data object.

content: MessageContent#

destination: Actor#

header: str | None = None#

sender: Actor#

time_received: float | None = None#

time_sent: float | None = None#

class MessageContent(data: dict, message: str | None = None)#

Bases: object

Message content data object.

data: dict#

message: str | None = None#

upstage.communications.processes module#

Communications process helper.

generate_comms_wait(incoming_store: Store, callback: Callable[[MessageContent], Any]) → Callable[[], Process]#

Create a process function to transfer communications to a callback.

This hides cleanup and other stability functions from the user.

Parameters:

incoming_store (A simpy or upstage store) – The store that is linked to a CommsManager instance.
callback (function) – The function to call with a received message
Returns
-------
function – An UPSTAGE process function that passes messages

Module contents#

Module for communications processes and data objects.