Package co.paralleluniverse.actors

Class Actor<Message,​V>

    • Constructor Detail

      • Actor

        public Actor​(java.lang.String name,
             MailboxConfig mailboxConfig)
        Creates a new actor.
        Parameters:
        name - the actor name (may be null).
        mailboxConfig - the actor's mailbox settings; if null, the default config - unbounded mailbox - will be used.

      • Actor

        protected Actor()
        This constructor must only be called by hot code-swap actors, and never, ever, called by application code.

      • Actor

        protected Actor​(Strand strand,
                java.lang.String name,
                MailboxConfig mailboxConfig)
        Creates a new actor.
        Parameters:
        strand - the actor's strand
        name - the actor name (may be null).
        mailboxConfig - the actor's mailbox settings; if null, the default config - unbounded mailbox - will be used.

    • Method Detail

      • newActor

        public static <T extends Actor<Message,​V>,​Message,​V> T newActor​(java.lang.Class<T> clazz,
                                                                                  java.lang.Object... params)
        Creates a new actor. The actor must have a public constructor that can take the given parameters.
        Type Parameters:
        T - The actor's type
        Message - The actor's message type.
        V - The actor's return value type.
        Parameters:
        clazz - The actor's class
        params - Parameters that will be passed to the actor class's constructor in order to construct a new instance.
        Returns:
        A new actor of type T.

      • newActor

        public static <T extends Actor<Message,​V>,​Message,​V> T newActor​(ActorSpec<T,​Message,​V> spec)
        Creates a new actor from an ActorSpec.
        Type Parameters:
        T - The actor's type
        Message - The actor's message type.
        V - The actor's return value type.
        Parameters:
        spec - The ActorSpec that defines how to build the actor.
        Returns:
        A new actor of type T.

      • setForwardWatch

        @Deprecated
public Actor<Message,​V> setForwardWatch​(boolean value)
        Deprecated.
        For use by non-Java, untyped languages only.

        If set to true, LifecycleMessage will, by default, return ExitMessages from watched actors to be returned by receive. This means that receive will return a message of a type that may not be Message, and therefore this value should only be set to true in untyped languages.

        Parameters:
        value -
        Returns:

      • getName

        public java.lang.String getName()
        Returns this actor's name.
        Overrides:
        getName in class ActorImpl<Message>

      • setName

        public void setName​(java.lang.String name)
        Sets this actor's name. The name does not have to be unique, and may be null
        Overrides:
        setName in class ActorImpl<Message>
        Parameters:
        name -

      • spawn

        public ActorRef<Message> spawn​(StrandFactory sf)
        Starts a new fiber using the given scheduler and runs the actor in it. The fiber's name will be set to this actor's name.
        Parameters:
        sf - the factory (or scheduler) that will be used to create the actor's fiber.
        Returns:
        This actors' ActorRef

      • spawn

        public ActorRef<Message> spawn​(FiberFactory ff)
        Starts a new fiber using the given scheduler and runs the actor in it. The fiber's name will be set to this actor's name.
        Parameters:
        ff - the factory (or scheduler) that will be used to create the actor's fiber.
        Returns:
        This actors' ActorRef

      • spawn

        public ActorRef<Message> spawn()
        Starts a new fiber and runs the actor in it. The fiber's name will be set to this actor's name.
        Returns:
        This actors' ActorRef

      • spawnThread

        public ActorRef<Message> spawnThread()
        Starts a new thread and runs the actor in it. The fiber's name will be set to this actor's name.
        Returns:
        This actors' ActorRef

      • reinstantiate

        protected Actor<Message,​V> reinstantiate()
        Returns a "clone" of this actor, used by a supervisor to restart this actor if it dies.

        If this actor is supervised by a supervisor and was not created with the newActor factory method, then this method should be overridden.

        Returns:
        A new LocalActor instance that's a clone of this.

      • interrupt

        protected final void interrupt()
        Interrupts the actor's strand.
        Specified by:
        interrupt in class ActorImpl<Message>

      • currentActor

        public static <M,​V> Actor<M,​V> currentActor()
        Returns the actor currently running in the current strand.

      • ref

        public ActorRef<Message> ref()
        Returns the ActorRef to this actor, if it has been started.
        Overrides:
        ref in class ActorImpl<Message>
        Returns:
        the ActorRef of this actor if it has been started, or null otherwise.

      • self

        protected ActorRef<Message> self()
        Returns the ActorRef to this actor, if it has been started.
        Returns:
        the ActorRef of this actor if it has been started, or null otherwise.

      • getQueueLength

        public final int getQueueLength()
        Returns the number of messages currently waiting in the mailbox.

      • mailbox

        protected final Mailbox<java.lang.Object> mailbox()
        Returns this actor's mailbox channel.
        Overrides:
        mailbox in class ActorImpl<Message>

      • internalSend

        protected void internalSend​(java.lang.Object message)
        Description copied from class: ActorImpl
        For internal use
        Specified by:
        internalSend in class ActorImpl<Message>

      • receive

        public final Message receive()
                      throws SuspendExecution,
                             java.lang.InterruptedException
        Returns the next message from the mailbox. If no message is currently available, this method blocks until a message arrives.
        Specified by:
        receive in interface ReceivePort<Message>
        Returns:
        a message sent to this actor.
        Throws:
        java.lang.InterruptedException
        SuspendExecution

      • receive

        public final Message receive​(long timeout,
                             java.util.concurrent.TimeUnit unit)
                      throws SuspendExecution,
                             java.lang.InterruptedException
        Returns the next message from the mailbox. If no message is currently available, this method blocks until a message arrives, but no longer than the given timeout.
        Specified by:
        receive in interface ReceivePort<Message>
        Parameters:
        timeout - the maximum duration to block waiting for a message.
        unit - the time unit of the timeout.
        Returns:
        a message sent to this actor, or null if the timeout has expired.
        Throws:
        java.lang.InterruptedException
        SuspendExecution

      • receive

        public final Message receive​(Timeout timeout)
                      throws SuspendExecution,
                             java.lang.InterruptedException
        Returns the next message from the mailbox. If no message is currently available, this method blocks until a message arrives, but no longer than the given timeout.
        Specified by:
        receive in interface ReceivePort<Message>
        Parameters:
        timeout - the method will not block for longer than the amount remaining in the Timeout
        Returns:
        a message sent to this actor, or null if the timeout has expired.
        Throws:
        java.lang.InterruptedException
        SuspendExecution

      • tryReceive

        public final Message tryReceive()
        Retrieves a message from the mailbox if one is available. This method never blocks.
        Specified by:
        tryReceive in interface ReceivePort<Message>
        Returns:
        a message, or null if one is not immediately available.

      • filterMessage

        protected Message filterMessage​(java.lang.Object m)
        All messages received from the mailbox are passed to this method. If this method returns a non-null value, this value will be returned from the receive methods. If it returns null, then receive will keep waiting.

        By default, this message passes all LifecycleMessage messages to handleLifecycleMessage, while other messages are returned (and will be returned by receive.

        Parameters:
        m - the message

      • isClosed

        public final boolean isClosed()
        Description copied from interface: PortAutoCloseable
        Tests whether the channel has been closed and no more messages await in the channel. If this method returns true all future calls to receive are guaranteed to return null, and calls to receive on a primitive channel will throw a EOFException.
        Specified by:
        isClosed in interface PortAutoCloseable
        Returns:
        true if the channels has been closed and no more messages will be received; false otherwise.

      • close

        public void close()
        Description copied from interface: PortAutoCloseable
        Closes the channel so that no more messages could be sent to it. Messages already sent to the channel will still be received.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface PortAutoCloseable
        Overrides:
        close in class ActorImpl<Message>

      • get

        public final V get()
            throws java.lang.InterruptedException,
                   java.util.concurrent.ExecutionException
        Specified by:
        get in interface Joinable<Message>
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException

      • get

        public final V get​(long timeout,
                   java.util.concurrent.TimeUnit unit)
            throws java.lang.InterruptedException,
                   java.util.concurrent.ExecutionException,
                   java.util.concurrent.TimeoutException
        Specified by:
        get in interface Joinable<Message>
        Throws:
        java.lang.InterruptedException
        java.util.concurrent.ExecutionException
        java.util.concurrent.TimeoutException

      • join

        @Suspendable
public final void join()
                throws java.util.concurrent.ExecutionException,
                       java.lang.InterruptedException
        Specified by:
        join in interface Joinable<Message>
        Throws:
        java.util.concurrent.ExecutionException
        java.lang.InterruptedException

      • join

        @Suspendable
public final void join​(long timeout,
                       java.util.concurrent.TimeUnit unit)
                throws java.util.concurrent.ExecutionException,
                       java.lang.InterruptedException,
                       java.util.concurrent.TimeoutException
        Specified by:
        join in interface Joinable<Message>
        Throws:
        java.util.concurrent.ExecutionException
        java.lang.InterruptedException
        java.util.concurrent.TimeoutException

      • isStarted

        public final boolean isStarted()
        Tests whether this actor has been started, i.e. whether the strand executing it has been started.

      • isDone

        public final boolean isDone()
        Tests whether this actor has terminated.
        Specified by:
        isDone in interface Joinable<Message>

      • verifyInActor

        protected final void verifyInActor()
        Tests whether this code is executing in this actor's strand, and throws a ConcurrencyException if not.
        See Also:
        isInActor()

      • verifyOnActorStrand

        protected final void verifyOnActorStrand()

      • isInActor

        protected final boolean isInActor()
        Tests whether this code is executing in this actor's strand.

      • getActor

        public static Actor getActor​(Strand s)
        Returns the actor associated with the given strand, or null if none is.

      • doRun

        protected abstract V doRun()
                    throws java.lang.InterruptedException,
                           SuspendExecution
        An actor must implement this method, which contains the actor's logic. This method begins executing on the actor's strand.

        Upon a hot code-swap, this method is re-executed, so it is this method's responsibility to check this actor's state (which may not be blank after a code-swap) when it begins.

        Returns:
        The actor's return value, which can be obtained with get().
        Throws:
        java.lang.InterruptedException
        SuspendExecution

      • handleLifecycleMessage

        protected Message handleLifecycleMessage​(LifecycleMessage m)
        This method is called by this class during a call to any of the receive methods if a LifecycleMessage is found in the mailbox. By default, if the message is an ExitMessage and its watch is null, i.e. it's a result of a link rather than a watch, it will throw a LifecycleException, which will, in turn, cause this exception to be thrown by the call to receive. This method is not allowed to block. If you want to block as a result of a lifecycle message, return the message from this method (rather than returning null), and have it processed by the caller to receive.
        Parameters:
        m - the message
        Returns:
        null if the message has been processed and should not be returned by receive

      • checkCodeSwap

        protected void checkCodeSwap()
                      throws SuspendExecution
        Tests whether this actor has been upgraded via hot code-swapping. If a new version of this actor is found, this method never returns (a special Error is thrown which causes the actor to restart).
        Throws:
        SuspendExecution

      • onCodeChange

        protected void onCodeChange()
        This method is called on an actor instance replacing an active instance via hot code-swapping. When this method is called, the fields of the old instance have been shalZlow-copied to this instance, but this instance has not yet started to run. This method should initialize any relevant state not copied from the old instance.

      • addLifecycleListener

        protected final void addLifecycleListener​(co.paralleluniverse.actors.LifecycleListener listener)
        Specified by:
        addLifecycleListener in class ActorImpl<Message>

      • getDeathCause

        protected final java.lang.Throwable getDeathCause()
        Returns this actor's cause of death
        Returns:
        the Throwable that caused this actor's death, or null if it died by natural causes, or if it not dead.

      • isRegistered

        public final boolean isRegistered()
        Tests whether this actor has been registered.
        Returns:
        true if the actor is registered; false otherwise.

      • throwIn

        public final void throwIn​(java.lang.RuntimeException e)
        Specified by:
        throwIn in class ActorImpl<Message>

      • checkThrownIn

        public final void checkThrownIn()
        Tests whether an exception has been thrown into this actor, and if so, throws it. This method must only be called within the actor's strand.

      • unlink

        public final Actor unlink​(ActorRef other)
        Un-links this actor from another. This operation is symmetric.
        Parameters:
        other - the other actor
        Returns:
        this
        See Also:
        link(ActorRef)

      • watch

        public final java.lang.Object watch​(ActorRef other)
        Makes this actor watch another actor. When the other actor dies, this actor receives an ExitMessage, that is handled by handleLifecycleMessage. This message does not cause an exception to be thrown, unlike the case where it is received as a result of a linked actor's death.

        Unlike a link, a watch is asymmetric, and it is also composable, namely, calling this method twice with the same argument would result in two different values returned, and in an ExitMessage to be received twice.

        Parameters:
        other - the other actor
        Returns:
        a watchId object that identifies this watch in messages, and used to remove the watch by the unwatch method.
        See Also:
        link(ActorRef), unwatch(ActorRef, Object)

      • unwatch

        public final void unwatch​(ActorRef other,
                          java.lang.Object watchId)
        Un-watches another actor.
        Parameters:
        other - the other actor
        watchId - the object returned from the call to watch(other)
        See Also:
        watch(ActorRef)

      • register

        public final Actor<Message,​V> register​(java.lang.String name)
                                      throws SuspendExecution
        Registers this actor in the actor registry under the given name and sets this actor's name. This also creates a monitor for this actor.
        Parameters:
        name - the name of the actor in the registry, must be equal to the actor's name if it has one.
        Returns:
        this
        Throws:
        SuspendExecution

      • unregister

        public final Actor unregister()
        Unregisters this actor from the actor registry.
        Returns:
        this

      • migrateAndRestart

        public void migrateAndRestart()
                       throws SuspendExecution
        Suspends and migrates the actor in such a way that when it is later hired, the actor is restarted (i.e., its `doRun` method will be called again and run from the top), but the current value of the actor's fields will be preserved. This method never returns.
        Throws:
        SuspendExecution

      • migrate

        public void migrate()
             throws SuspendExecution
        Suspends and migrate the actor. This method suspends the fiber the actor is running in (and is therefore available only for actors running in fibers), so that when the actor is hired, it will continue execution from the point this method was called. This method must be called on a fiber.
        Throws:
        SuspendExecution

      • writeReplace

        protected final java.lang.Object writeReplace()
                                       throws java.io.ObjectStreamException
        Throws:
        java.io.ObjectStreamException

      • readResolve

        protected java.lang.Object readResolve()
                                throws java.io.ObjectStreamException
        Throws:
        java.io.ObjectStreamException

      • monitor

        public final co.paralleluniverse.actors.ActorMonitor monitor()
        Starts a monitor that exposes information about this actor via a JMX MBean.
        Returns:
        the monitor

      • setMonitor

        public final void setMonitor​(co.paralleluniverse.actors.ActorMonitor monitor)
        Sets the actor's monitor
        Parameters:
        monitor - the monitor

      • stopMonitor

        public final void stopMonitor()
        Shuts down the actor's monitor.

      • getMonitor

        public final co.paralleluniverse.actors.ActorMonitor getMonitor()

      • monitorAddDeath

        protected final void monitorAddDeath​(java.lang.Object reason)

      • monitorAddMessage

        protected final void monitorAddMessage()

      • monitorSkippedMessage

        protected final void monitorSkippedMessage()

      • monitorResetSkippedMessages

        protected final void monitorResetSkippedMessages()