XActor API

Staring and Stopping the Actor System

xactor.actor_system.start(actor_id, cls, *args, **kwargs)

Start the actor system.

This method starts up the rank actors, creates the main actor on the MASTER_RANK (using given arguments), and sends it the “main” message.

Parameters
  • actor_id (str) – ID of the main actor.

  • cls (type) – Class used to instantiate the main actor on the MASTER_RANK

  • *args (list) – Positional arguments for the constructor

  • **kwargs (dict) – Keyword arguments for the constructor

xactor.actor_system.stop()

Stop the actor system.

Creating and Deleting Actors

xactor.actor_system.create_actor(rank, actor_id, cls, *args, **kwargs)

Create an actor on the given rank.

Parameters
  • rank (int or list of ints) – Rank(s) on which actor is to be created. See send for how rank is processed.

  • actor_id (str) – ID of the new actor

  • cls (type) – Class used to instantiate the new actor

  • *args (list) – Positional arguments for the constructor

  • **kwargs (dict) – Keyword arguments for the constructor

xactor.actor_system.delete_actors(rank, actor_ids)

Delete the given actors on the given rank.

Parameters
  • rank (int or list of ints) – Rank(s) on which actor is to be created. See send for how rank is processed.

  • actor_ids (list of str) – IDs of actors to be deleted

Sending Messages

xactor.actor_system.send(rank, actor_id, message, immediate=True)

Send the message to the given actor on the given rank.

Parameters
  • rank (int or list of ints) – Destination rank(s) on which the actor resides. If rank is an iterable, send it to all ranks in the iterable. if rank == EVERY_RANK, message is sent to all ranks.

  • actor_id (str) – Actor to whom the message is to be sent

  • message (Message) – Message to be sent

  • immediate (bool) – If true flush out buffer to destination ranks

xactor.actor_system.flush(rank=None)

Flush out the send buffers.

Parameters

rank (int or None) – If None, flush out all buffers otherwise, flush out only the buffer to the given rank.

Directly Accessing Local Actors

xactor.actor_system.local_actor(actor_id)

Return the reference to the local actor.

Parameters

actor_id (str) – ID of the already existing actor.

Returns

Return type

A reference to the local actor or None if the actor doesn’t exist.

Nodes and Ranks

xactor.actor_system.ranks()

Return all ranks running the actor system.

Returns

ranks – An iterable of node ranks

Return type

iterable of int

xactor.actor_system.nodes()

Return all nodes running the actor system.

Returns

nodes – List of of node names

Return type

list

xactor.actor_system.node_ranks(node)

Return the ranks on the given node.

Parameters

node (str) – The name of a node name

Returns

ranks – List of ranks running on the given node.

Return type

list of int

xactor.actor_system.current_rank()

Return the rank of current process.

Returns

rank – Rank of the current process

Return type

int

xactor.actor_system.MASTER_RANK

Constant used to refer to the designated master rank.

xactor.actor_system.EVERY_RANK

Constant used to send a message to all ranks.

Message

class xactor.message.Message(method: str, args: list = <factory>, kwargs: dict = <factory>)

A Message.

A message corresponds to a method call on the remote actor. A message objects contains the name of the method, and the parameters to be passed when calling.

A message can be constructed directly, or by using a ActorProxy object.

method

Name of the method

Type

str

args

Positional arguments

Type

list

kwargs

Keyword arguments

Type

dict

ActorProxy

class xactor.actor_proxy.ActorProxy(rank=None, actor_id=None)

A proxy of an actor.

This class provides syntactic sugar for creating and sending messages to remote actors.

The following code shows how to send messages using actor proxy

>>> actor = ActorProxy(rank, actor_id)
>>> actor.method(*args, **kwargs)

The above does the same thing as the following code:

>>> message = Message("method", args, kwargs)
>>> send(rank, actor_id, message)

NOTE: When constructing messages using actor proxy, the keyword argument buffer_ is handled specially. If present and true, it is taken to indicate that the send should be called with immediate=False.

rank\_

Rank of the remote actor (see send for details)

Type

int or list of ints

actor_id\_

ID of the remote actor

Type

str

create_actor_(cls, *args, **kwargs)

Create the remote actor.

Parameters
  • cls (type) – Class used to instantiate the new actor

  • *args (list) – Positional arguments for the constructor

  • **kwargs (dict) – Keyword arguments for the constructor

Utilities

xactor.actor_system.getLogger(name)

Return a logger with the given name and the world rank appended to it.

Parameters

name (str) – Name of the logger

Returns

logger – A logging.Logger object

Return type

logging.Logger

Environment Variables

Enironment variable processing.

The following environment variables can be used to configure XActor’s runtime behavior.

Debug mode configuration variables

The following two environment variables are only relevant if Python is not running in optimized mode that is with the -O flag.

XACTOR_PROFILE_DIR:
If defined XActor will profile the actor method calls and will write the profiling results at the end of the program in files in the given directory. One file will be created per rank.
Example usage: export XACTOR_PROFILE_DIR=/tmp
XACTOR_SEND_TRACEBACK:
If defined XActor will send the sender traceback along with messages. The traceback is printed if there is a problem at the receiver when trying to execute the called method on the actor.
Example usage: export XACTOR_SEND_TRACEBACK=1

Runtime configuration variables

XACTOR_MAX_MESSAGE_SIZE:
Maximum expected size of a single message sent using XActor. Note this is the size, in bytes, of the result of pickling the message.
Default: 4194304 (4MB)
Example usage: export XACTOR_MAX_MESSAGE_SIZE=4194304
XACTOR_MIN_SEND_SIZE:
Send buffers will be flushed once it is full beyond this size.
Default: 65536 (64KB)
Example usage: export XACTOR_MIN_SEND_SIZE=65536
XACTOR_NUM_RECV_BUFFERS:
Number of receive buffers to post (on each rank) at a time.
Default: 1
Example usage: export XACTOR_NUM_RECV_BUFFERS=1
XACTOR_MAX_SEND_BUFFERS:
Maximum number of send buffers (on each rank) at a time. XActor’s send method will block once this number is reached.
Default: 2
Example usage: export XACTOR_MAX_SEND_BUFFERS=2