-
Notifications
You must be signed in to change notification settings - Fork 14
User Guide
Jumi Actors is somewhat different from other actor libraries:
The main difference is that with Jumi Actors the thread where each actor runs is determined explicitly when the actor is created. This makes it possible for an actor to for example create callbacks as one-off actors (usually inner classes or another interface of the same class) to receive responses from other actors and share some mutable state between those callbacks and the surrounding actor.
Another difference is that individual actors do not need to be stopped explicitly, but they will be garbage collected by the JVM after nobody holds an ActorRef to them. Instead, the ActorThreads must be explicitly stopped and that will stop all actors which were bound to the same thread.
To get started with Jumi Actors, add to your project a dependency to jumi-actors and read through the examples:
-
The comments in HelloWorld explain the basic concepts.
-
Pi gives an example of a couple of communicating actors and the use of worker threads. This is based on the example in Akka's Getting Started Tutorial so that you can compare these two actor libraries.
-
PiTest shows how code using Jumi Actors can be unit tested without the container, and how integration/collaboration tests can be written easier using SingleThreadedActors.
You may also browse the Javadocs.
Most people might prefer using the reflection based DynamicEventizerProvider which supports all actor interfaces. But it's also possible to use the jumi-actors-generator to generate the eventizers at compile time and thus avoid reflection.
Add jumi-actors-generator as a dependency (in Maven's provided scope), add the @GenerateEventizer annotation on the event interface, and the Java compiler will automatically generate the eventizers when the interface is compiled. The generated eventizers can be passed to the actors container by using ComposedEventizerProvider.
It's also possible to use the jumi-actors-maven-plugin to generate the eventizers at compile time and thus avoid reflection. The generated eventizers can be passed to the actors container by using ComposedEventizerProvider.
To learn how to use that Maven plugin, see jumi-core/pom.xml and jumi-daemon's Main.
Jumi has a Java Agent which can be used to check at runtime that the instances of all classes annotated with @NotThreadSafe are only accessed from one thread. If such an object is called from two different threads (during its lifetime), an exception will be thrown. This is a stronger guarantee than not being accessed from two threads concurrently, but works well with Jumi Actors' threading model.
The thread-safety-agent can be used with the -javaagent JVM option. For an example see Jumi's end-to-end-tests/pom.xml.