aiomas.agent

This module implements the base class for agents (Agent) and containers for agents (Container).

Every agent must live in a container. A container can contain one ore more agents. Containers are responsible for making connections to other containers and agents. They also provide a factory function for spawning new agent instances and registering them with the container.

Thus, the Agent base class is very light-weight. It only has a name, a reference to its container and an RPC router (see aiomas.rpc).

class aiomas.agent.SSLCerts(cafile, certfile, keyfile)

namedtuple() storing the names of a CA file, a certificate file and the associated private key file.

See also aiomas.util.make_ssl_server_context() and aiomas.util.make_ssl_client_context().

cafile

Alias for field number 0

certfile

Alias for field number 1

keyfile

Alias for field number 2

class aiomas.agent.Container(base_url, clock, connect_kwargs)[source]

Container for agents.

It can instantiate new agents via spawn() and can create connections to other agents (via connect()).

In order to destroy a container and close all of its sockets, call shutdown().

You should not instantiate codecs directly but use the create() coroutine instead.

classmethod create(addr, *, clock=None, codec=None, extra_serializers=None, ssl=None, async=False)[source]

Instantiate a container and create a server socket for it.

This function is a classmethod and coroutine.

Parameters:
  • addr

    is the address that the server socket is bound to. It may be a (host, port) tuple or a path for a Unix domain socket.

    If host is '0.0.0.0' / '::', the server is bound to all available IPv4 or IPv6 interfaces respectively. If host is None or '', the server is bound to all available IPv4 and IPv6 interfaces. In these cases, the machine’s FQDN (see socket.getfqdn()) should be resolvable and point to that machine as it will be used for the agent’s addresses.

    If host is a simple (IPv4 or IPv6) IP address, it will be used for the agent’s addresses as is.

  • clock

    can be an instance of BaseClock.

    It allows you to decouple the container’s (and thus, its agent’s) time from the system clock. This makes it easier to integrate your system with other simulators that may provide a clock for you or to let your MAS run as fast as possible.

    By default, the real-time AsyncioClock will be used.

  • codec – can be a Codec subclass (not an instance!). JSON is used by default.
  • extra_serializers – is an optional list of extra serializers for the codec. The list entries need to be callables that return a tuple with the arguments for add_serializer().
  • ssl – allows you to enable TLS for all incoming and outgoing TCP connections. It may either be an SSLCerts instance or a tuple containing two SSLContext instances, where the first one will be used for the server socket, the second one for client sockets.
  • async – must be set to True if the event loop is already running when you call this method. This function then returns a coroutine that you need to yield from in order to get the container. By default it will block until the server has been started and return the container.
Returns:

a fully initialized Container instance if async is False or else a coroutine returning the instance when it is done.

Invocation examples:

# Synchronous:
container = Container.create(...)

# Asynchronous:
container = yield from Container.create(..., async=True)
clock

The clock of the container. Instance of aiomas.clocks.BaseClock.

connect(url)[source]

Connect to the argent available at url and return a proxy to it.

url is a string <protocol>://<addr>//<agent-id> (e.g., 'tcp://localhost:5555/0').

shutdown(async=False)[source]

Close the container’s server socket and the RPC services for all outgoing TCP connections.

If async is left to False, this method calls asyncio.BaseEventLoop.run_until_complete() in order to wait until all sockets are closed.

If the event loop is already running when you call this method, set async to True. The return value then is a coroutine that you need to yield from in order to actually shut the container down:

yield from container.shutdown(async=True)
validate_aid(aid)[source]

Return the class name for the agent represented by aid if it exists or None.

class aiomas.agent.Agent(container)[source]

Base class for all agents.

router

Descriptor that creates an RPC Router for every agent instance.

You can override this in a sub-class if you need to. (Usually, you don’t.)

container

The Container that the agent lives in.

addr

The agent’s address.