# Actors

class `pykka.``Actor`(*args, **kwargs)

  To create an actor:

  1. subclass one of the `Actor` implementations:
     - `ThreadingActor`
     - `GeventActor`
     - `EventletActor`
  2. implement your methods, including `__init__()`, as usual,
  3. call `Actor.start()` on your actor class, passing the method any arguments for your constructor.

  To stop an actor, call `Actor.stop()` or `ActorRef.stop()`.

  For example:

      import pykka

      class MyActor(pykka.ThreadingActor):
          def __init__(self, my_arg=None):
              super().__init__()
              ... # My optional init code with access to start() arguments

          def on_start(self):
              ... # My optional setup code in same context as on_receive()

          def on_stop(self):
              ... # My optional cleanup code in same context as on_receive()

          def on_failure(self, exception_type, exception_value, traceback):
              ... # My optional cleanup code in same context as on_receive()

          def on_receive(self, message):
              ... # My optional message handling code for a plain actor

          def a_method(self, ...):
              ... # My regular method to be used through an ActorProxy

      my_actor_ref = MyActor.start(my_arg=...)
      my_actor_ref.stop()

  classmethod `start`(*args, **kwargs)

    Start an actor and register it in the `ActorRegistry`.

    Any arguments passed to `start()` will be passed on to the class constructor.

    Behind the scenes, the following is happening when you call `start()`:

    1. The actor is created:
       1. `actor_urn` is initialized with the assigned URN.
       2. `actor_inbox` is initialized with a new actor inbox.
       3. `actor_ref` is initialized with a `pykka.ActorRef` object for safely communicating with the actor.
       4. At this point, your `__init__()` code can run.
    2. The actor is registered in `pykka.ActorRegistry`.
    3. The actor receive loop is started by the actor’s associated thread/greenlet.

    Returns: | a `ActorRef` which can be used to access the actor in a safe manner

  `actor_urn` = None

    The actor URN string is a universally unique identifier for the actor. It may be used for looking up a specific actor using `ActorRegistry.get_by_urn()`.

  `actor_inbox` = None

    The actor’s inbox. Use `ActorRef.tell()`, `ActorRef.ask()`, and friends to put messages in the inbox.

  `actor_stopped` = None

    A `threading.Event` representing whether or not the actor should continue processing messages. Use `stop()` to change it.

  `actor_ref` = None

    The actor’s `ActorRef` instance.

  `stop`()

    Stop the actor.

    It’s equivalent to calling `ActorRef.stop()` with `block=False`.

  `on_start`()

    Hook for doing any setup that should be done after the actor is started, but before it starts processing messages.

    For `ThreadingActor`, this method is executed in the actor’s own thread, while `__init__()` is executed in the thread that created the actor.

    If an exception is raised by this method the stack trace will be logged, and the actor will stop.

  `on_stop`()

    Hook for doing any cleanup that should be done after the actor has processed the last message, and before the actor stops.

    This hook is not called when the actor stops because of an unhandled exception. In that case, the `on_failure()` hook is called instead.

    For `ThreadingActor` this method is executed in the actor’s own thread, immediately before the thread exits.

    If an exception is raised by this method the stack trace will be logged, and the actor will stop.

  `on_failure`(exception_type, exception_value, traceback)

    Hook for doing any cleanup after an unhandled exception is raised, and before the actor stops.

    For `ThreadingActor` this method is executed in the actor’s own thread, immediately before the thread exits.

    The method’s arguments are the relevant information from `sys.exc_info()`.

    If an exception is raised by this method the stack trace will be logged, and the actor will stop.

  `on_receive`(message)

    May be implemented for the actor to handle regular non-proxy messages.

    Parameters: | message (any) – the message to handle
    Returns: | anything that should be sent as a reply to the sender

class `pykka.``ActorRef`(actor)

  Reference to a running actor which may safely be passed around.

  `ActorRef` instances are returned by `Actor.start()` and the lookup methods in `ActorRegistry`. You should never need to create `ActorRef` instances yourself.

  Parameters: | actor (`Actor`) – the actor to wrap

  `actor_class` = None

    The class of the referenced actor.

  `actor_urn` = None

    See `Actor.actor_urn`.

  `actor_inbox` = None

    See `Actor.actor_inbox`.

  `actor_stopped` = None

    See `Actor.actor_stopped`.

  `is_alive`()

    Check if actor is alive.

    This is based on the actor’s stopped flag. The actor is not guaranteed to be alive and responding even though `is_alive()` returns `True`.

    Returns: | Returns `True` if actor is alive, `False` otherwise.

  `tell`(message)

    Send message to actor without waiting for any response.

    Will generally not block, but if the underlying queue is full it will block until a free slot is available.

    Parameters: | message (any) – message to send
    Raise: | `pykka.ActorDeadError` if actor is not available
    Returns: | nothing

  `ask`(message, block=True, timeout=None)

    Send message to actor and wait for the reply.

    The message can be of any type. If `block` is `False`, it will immediately return a `Future` instead of blocking.

    If `block` is `True`, and `timeout` is `None`, as default, the method will block until it gets a reply, potentially forever. If `timeout` is an integer or float, the method will wait for a reply for `timeout` seconds, and then raise `pykka.Timeout`.

    Parameters:

    - message (any) – message to send
    - block (boolean) – whether to block while waiting for a reply
    - timeout (float or `None`) – seconds to wait before timeout if blocking

    Raise: | `pykka.Timeout` if timeout is reached if blocking
    Raise: | any exception returned by the receiving actor if blocking
    Returns: | `pykka.Future`, or response if blocking

  `stop`(block=True, timeout=None)

    Send a message to the actor, asking it to stop.

    Returns `True` if actor is stopped or was being stopped at the time of the call. `False` if actor was already dead. If `block` is `False`, it returns a future wrapping the result.

    Messages sent to the actor before the actor is asked to stop will be processed normally before it stops.

    Messages sent to the actor after the actor is asked to stop will be replied to with `pykka.ActorDeadError` after it stops.

    The actor may not be restarted.

    `block` and `timeout` works as for `ask()`.

    Returns: | `pykka.Future`, or a boolean result if blocking

  `proxy`()

    Wraps the `ActorRef` in an `ActorProxy`.

    Using this method like this:

        proxy = AnActor.start().proxy()

    is analogous to:

        proxy = ActorProxy(AnActor.start())

    Raise: | `pykka.ActorDeadError` if actor is not available
    Returns: | `pykka.ActorProxy`