Package org.daiitech.naftah.builtin.utils.concurrent

Class Actor<T>

java.lang.Object
org.daiitech.naftah.builtin.utils.concurrent.Actor<T>
Type Parameters:
T - the type of messages this actor can receive
All Implemented Interfaces:
Runnable
public abstract class Actor<T> extends Object implements Runnable
An abstract actor implementation for message-driven concurrency.

Each Actor maintains its own mailbox and processes messages sequentially on a dedicated thread. Messages are sent asynchronously and handled via the handle(Object) method.

Key features:

  • Each actor has a private BlockingQueue for incoming messages.
  • The actor runs on a dedicated thread that processes messages sequentially.
  • Provides lifecycle management: stop(), join(), isAlive().
  • Supports custom cleanup logic via a cleaner Runnable.

Author:
Chakib Daii

  • Field Details

    • mailbox

      private final BlockingQueue<T> mailbox

    • thread

      private final Thread thread

    • name

      private final String name

    • context

      private final DefaultContext context

    • initBlock

      private final Runnable initBlock

    • running

      private boolean running

  • Constructor Details

    • Actor

      private Actor(String name, DefaultContext context, Runnable initBlock, Runnable cleaner)
      Constructs an actor with a given name and a cleanup task.
      Parameters:
      name - the name of the actor
      context - the execution context
      initBlock - the code block that initiates the actor
      cleaner - a cleanup runnable to execute when the actor terminates

  • Method Details

    • of

      public static <T> Actor<T> of(String name, DefaultContext context, Runnable initBlock, Consumer<T> consumer, Runnable cleaner)
      Creates a simple actor from a Consumer for handling messages.
      Type Parameters:
      T - the message type
      Parameters:
      name - the name of the actor
      context - the execution context
      initBlock - the codee block that initiates the actor
      consumer - a consumer that processes messages
      cleaner - a cleanup task executed when the actor stops
      Returns:
      a new Actor instance

    • send

      public boolean send(T msg)
      Sends a message to this actor asynchronously.
      Parameters:
      msg - the message to send
      Returns:
      true if the message was successfully enqueued, false otherwise

    • receive

      protected T receive() throws InterruptedException
      Receives the next message from the mailbox, blocking if none are available.
      Returns:
      the next message
      Throws:
      InterruptedException - if the thread is interrupted while waiting

    • handle

      public abstract void handle(T message) throws Exception
      Handles a single message from the mailbox.

      Must be implemented by subclasses. Any exceptions should be handled to prevent the actor thread from terminating unexpectedly.

      Parameters:
      message - the message to handle
      Throws:
      Exception - if an error occurs during message handling

    • run

      public void run()
      Specified by:
      run in interface Runnable

    • stop

      public void stop()
      Stops this actor gracefully by setting the running flag to false and interrupting its thread.

    • join

      public void join() throws InterruptedException
      Waits for the actor thread to terminate.
      Throws:
      InterruptedException - if interrupted while waiting

    • isAlive

      public boolean isAlive()
      Checks whether the actor's thread is alive.
      Returns:
      true if the thread is alive, false otherwise

    • getThread

      public Thread getThread()
      Returns the underlying thread of this actor.
      Returns:
      the actor's thread

    • getName

      public String getName()
      Returns the name of the actor.
      Returns:
      the actor's name

    • isRunning

      public boolean isRunning()
      Checks whether the actor is currently running.
      Returns:
      true if running, false otherwise

    • toString

      public String toString()
      Returns a string representation of this Actor.

      The format is "<ممثل {name}>", where "ممثل" means "Actor" in Arabic and {name} is the name of the actor.

      This is primarily intended for debugging or logging to identify the actor instance by its name.

      Overrides:
      toString in class Object
      Returns:
      a string representation of the actor