layout: docs.hbs

title: Props

Props

Props is a configuration class to specify options for the creation of actors, think of it as an immutable and thus freely shareable recipe for creating an actor including associated deployment information (e.g. which dispatcher to use, see more below). Here are some examples of how to create a Props instance.

Props props1 = Props.Create(typeof(MyActor));
Props props2 = Props.Create(() => new MyActor(..), "...");
Props props3 = Props.Create<MyActor>();

Warning
In the second line, using new; Do note that the arguments passed in will be evaluated once, when the Props are created. This is because the arguments can be passed to remote systems for remote deployment. The behavior is somewhat odd since a lambda containing a new statement generally evaluates the entire expression every time it is invoked.

Recommended Practices

It is a good idea to provide static factory methods on the UntypedActor which help keep the creation of suitable Props as close to the actor definition as possible. This also allows usage of the Creator-based methods which statically verify that the used constructor actually exists instead of relying only on a runtime check.

public class DemoActor : ReceiveActor
{
    /// <summary>
    /// Create Props for an actor of this type.
    /// </summary>
    /// <param name="magicNumber">
    /// The magic number to be passed to this actor’s constructor.
    /// </param>
    /// <returns>
    /// A Props for creating this actor, which can then be further configured
    /// (e.g. calling `.withDispatcher()` on it)
    /// </returns>
    public static Props CreateProps(int magicNumber)
    {
        return Props.Create(() => new DemoActor(magicNumber));
    }

    private int magicNumber;

    public DemoActor(int magicNumber)
    {
        this.magicNumber = magicNumber;
        ...some receive declarations here
        //Receive<string>(str => ..);
    }
}

system.ActorOf(DemoActor.CreateProps(42), "demo");

Creating Actors with Props

Actors are created by passing a Props instance into the ActorOf factory method which is available on ActorSystem and ActorContext.

// ActorSystem is a heavy object: create only one per application
ActorSystem system = ActorSystem.Create("MySystem");
IActorRef myActor = system.ActorOf(Props.Create(typeof(MyActor)), "myactor");

Using the ActorSystem will create top-level actors, supervised by the actor system’s provided guardian actor, while using an actor’s context will create a child actor.

public class A : ReceiveActor
{
    IActorRef child = Context.ActorOf(Props.Create(typeof(MyActor)), "myChild");
    // plus some behavior ...
}

It is recommended to create a hierarchy of children, grand-children and so on such that it fits the logical failure-handling structure of the application, see Actor Systems.

The call to ActorOf returns an instance of IActorRef. This is a handle to the actor instance and the only way to interact with it. The IActorRef is immutable and has a one to one relationship with the Actor it represents. The IActorRef is also serializable and network-aware. This means that you can serialize it, send it over the wire and use it on a remote host and it will still be representing the same actor on the original node, across the network.

The name parameter is optional, but you should preferably name your actors, since that is used in log messages and for identifying actors. The name must not be empty or start with $, but it may contain URL encoded characters (eg. %20 for a blank space). If the given name is already in use by another child to the same parent an InvalidActorNameException is thrown.

Actors are automatically started asynchronously when created.