Actor (kontraktor 4.00 API)

java.lang.Object
- org.nustaq.kontraktor.Actors
- - org.nustaq.kontraktor.Actor<SELF>

All Implemented Interfaces:: Serializable, Executor, Monitorable

Direct Known Subclasses:: _AsyncClientSocket.CLSActor, Log, TCPClientConnector.RemotingHelper

public class Actor<SELF extends Actor>
extends Actors
implements Serializable, Monitorable, Executor

Baseclass for actor/eventloop implementations. Note that actors are not created using constructors. Use Actors.AsActor(..) to instantiate an actor instance. Example (public methods are automatically transformed to be async):

 public class MyActor extends Actor {

     // public async API
     public IPromise init() {..}
     public void asyncMessage(String arg) { .. }
     public IPromise asyncMessage(String arg) { .. }
     public void asyncMessage(int arg, Callback aCallback) { .. }

     // synchronous methods (safe as cannot be called by foreign threads)
     protected String syncMethod() { .. }
 }

 MyActor act = Actors.AsActor(MyActor.class);
 act.init().then( () -> { System.out.println("done"); }
 Object res = act.asyncMessage("Hello").await();

Note that unlike in other actor libraries, processing of Callback and Promise is transfered to the current actor thread, so its safe to close over actor state.

See Also:: Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Actor.ActorReport

Nested Classes
Modifier and Type	Class and Description
`static class`	`Actor.ActorReport`

Field Summary

Fields
Modifier and Type	Field and Description
`Queue`	`__cbQueue`
`RemoteConnection`	`__clientConnection`
`ConcurrentLinkedQueue<RemoteConnection>`	`__connections`
`Thread`	`__currentDispatcher`
`Queue`	`__mailbox`
`int`	`__mailboxCapacity`
`int`	`__mbCapacity`
`long`	`__remoteId`
`Scheduler`	`__scheduler`
`Actor`	`__self`
`boolean`	`__stopped`
`boolean`	`__throwExAtBlock`
`protected TicketMachine`	`__ticketMachine`
`static ThreadLocal<RemoteConnection>`	`connection` contains remote connection if current message came from remote
`static ThreadLocal<Actor>`	`sender` contains sender of a message if one actor messages to another actor

Fields inherited from class org.nustaq.kontraktor.Actors
CONT, DEFAULT_BOUNDED_QUEUE, DEFAULT_TIMOUT, defaultScheduler, delayedCalls, exec, instance, MAX_EXTERNAL_THREADS_POOL_SIZE, version

Constructor Summary

Constructors
Constructor and Description

Actor()
required by bytecode magic.

Constructors
Constructor and Description
`Actor()` required by bytecode magic.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`__addDeadLetter(Actor receiver, String methodName)`
`void`	`__addRemoteConnection(RemoteConnection con)`
`void`	`__addStopHandler(Callback<SELF> cb)`
`boolean`	`__dispatchRemoteCall(ObjectSocket objSocket, RemoteCallEntry rce, RemoteRegistry registry, List<IPromise> createdFutures, Object authContext, BiFunction<Actor,String,Boolean> callInterceptor)` called if a message invokation from remote is received
`Object`	`__enqueueCall(Actor receiver, String methodName, Object[] args, boolean isCB)`
`Method`	`__getCachedMethod(String methodName, Actor actor, BiFunction<Actor,String,Boolean> callInterceptor)`
`void`	`__removeRemoteConnection(RemoteConnection con)`
`void`	`__stop()`
`protected void`	`__stopImpl()`
`void`	`__submit(Runnable toRun)`
`IPromise`	`ask(String messageId, Object... args)` generic method for untyped remoting.
`IPromise`	`askMsg(String messageId, Object... args)` generic method for untyped messages.
`void`	`asyncstop()`
`protected void`	`checkThread()` Debug method.
`void`	`close()` closes associated remote connection(s) if present.
`protected void`	`closeCurrentClient()` closes the connection to the remote client which has sent currently executing message.
`static Actor`	`current()`
`void`	`delayed(long millis, Runnable toRun)` schedule an action or call delayed.
`<T> IPromise<T>`	`exec(Callable<T> callable)` execute a callable asynchronously (in a different thread) and return a future of the result (delivered in caller thread).
`void`	`execute(Runnable command)` just enqueue given runable to this actors mailbox and execute on the actor's thread WARNING: the similar named method exec() works different (bad naming)
`SELF`	`getActor()`
`Actor`	`getActorRef()`
`int`	`getCallbackSize()` WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
`protected ConcurrentLinkedQueue<RemoteConnection>`	`getConnections()`
`DispatcherThread`	`getCurrentDispatcher()`
`ActorProxyFactory`	`getFactory()`
`int`	`getMailboxSize()` WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
`int`	`getQSizes()` WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
`IPromise`	`getReport()`
`Scheduler`	`getScheduler()`
`IPromise<Monitorable[]>`	`getSubMonitorables()`
`protected boolean`	`getThrowExWhenBlocked()`
`protected void`	`hasStopped()` override to clean up / stop dependend actors
`static boolean`	`inside()`
`protected <T> T`	`inThread(Actor proxy, T cbInterface)` wraps an interface into a proxy of that interface.
`boolean`	`isCallbackQPressured()` WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
`boolean`	`isEmpty()`
`boolean`	`isMailboxPressured()` WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
`boolean`	`isProxy()`
`boolean`	`isPublished()`
`boolean`	`isRemote()`
`boolean`	`isStopped()` synchronous method returning true in case this actor is stopped
`IPromise`	`ping()` can be used to wait for all messages having been processed and get a signal from the returned future once this is complete
`protected SELF`	`self()` use this to call public methods using actor-dispatch instead of direct in-thread call.
`protected void`	`serialOn(Object transactionKey, Consumer<IPromise> toRun)` enforce serial execution of asynchronous tasks.
`SELF`	`setThrowExWhenBlocked(boolean b)` tellMsg the execution machinery to throw an ActorBlockedException in case the actor is blocked trying to put a message on an overloaded actor's mailbox/queue.
`void`	`stop()` stop receiving events.
`void`	`stopSafeClose()` avoids exception when closing an actor after stop has been called.
`void`	`tell(String messageId, Object... args)` generic method for untyped remoting.
`void`	`tellMsg(String messageId, Object... args)` generic method for untyped messages.
`void`	`transferTo(Actor target)` only meaningful if this actor is a buffered actor (failover/reconnect scenarios).

Methods inherited from class org.nustaq.kontraktor.Actors
AddDeadLetter, all, all, all, allMapped, AsActor, AsActor, AsActor, AsActor, AsBufferedActor, AsUntypedActor, awaitAll, awaitAll, awaitAll, awaitAll, complete, complete, DeadLetters, InThread, isComplete, isCont, isError, isErrorOrComplete, isResult, isTimeout, promise, race, race, reject, resolve, resolve, stream, SubmitDelayed, yield, yield, yieldCallbacks

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - sender
```
public static ThreadLocal<Actor> sender
```
    contains sender of a message if one actor messages to another actor
  - connection
```
public static ThreadLocal<RemoteConnection> connection
```
    contains remote connection if current message came from remote
  - __mailbox
```
public Queue __mailbox
```
  - __mbCapacity
```
public int __mbCapacity
```
  - __cbQueue
```
public Queue __cbQueue
```
  - __currentDispatcher
```
public Thread __currentDispatcher
```
  - __scheduler
```
public Scheduler __scheduler
```
  - __stopped
```
public volatile boolean __stopped
```
  - __self
```
public Actor __self
```
  - __remoteId
```
public long __remoteId
```
  - __throwExAtBlock
```
public boolean __throwExAtBlock
```
  - __connections
```
public volatile ConcurrentLinkedQueue<RemoteConnection> __connections
```
  - __clientConnection
```
public RemoteConnection __clientConnection
```
  - __mailboxCapacity
```
public int __mailboxCapacity
```
  - __ticketMachine
```
protected TicketMachine __ticketMachine
```
- Constructor Detail
  - Actor
```
public Actor()
```
    required by bytecode magic. Use Actors.AsActor(..) to construct actor instances
- Method Detail
  - current
```
public static Actor current()
```
    Returns:
    
    current actor or throw an exception if not running inside an actor thread.
  - inside
```
public static boolean inside()
```
  - __submit
```
public void __submit(Runnable toRun)
```
  - self
```
protected SELF self()
```
    use this to call public methods using actor-dispatch instead of direct in-thread call. Important: When passing references out of your actor, always pass 'self()' instead of this !
    
    Returns:
  - getFactory
```
public ActorProxyFactory getFactory()
```
  - getActor
```
public SELF getActor()
```
    Returns:
    
    if this is an actorproxy, return the underlying actor instance, else return this Note: gets patched during proxy generation to guarantee correctness.
  - stop
```
public void stop()
```
    stop receiving events. If there are no actors left on the underlying dispatcher, the dispatching thread will be terminated.
  - isStopped
```
public boolean isStopped()
```
    synchronous method returning true in case this actor is stopped
  - isProxy
```
public boolean isProxy()
```
    Returns:
    
    wether this is the "real" implementation or the proxy object
  - askMsg
```
public IPromise askMsg(String messageId,
                       Object... args)
```
    generic method for untyped messages.
    
    Parameters:
    
    messageId -
    
    Returns:
  - tellMsg
```
public void tellMsg(String messageId,
                    Object... args)
```
    generic method for untyped messages.
    
    Parameters:
    
    messageId -
  - ask
```
public IPromise ask(String messageId,
                    Object... args)
```
    generic method for untyped remoting.
    
    Parameters:
    
    messageId -
    
    Returns:
  - tell
```
public void tell(String messageId,
                 Object... args)
```
    generic method for untyped remoting.
    
    Parameters:
    
    messageId -
  - exec
```
public <T> IPromise<T> exec(Callable<T> callable)
```
    execute a callable asynchronously (in a different thread) and return a future of the result (delivered in caller thread). Can be used to isolate blocking operations WARNING: do not access local actor state (instance fields) from within the callable (=hidden parallelism). WARNING: a similar named method execute() works different (bad naming)
    
    Type Parameters:
    
    T -
    
    Parameters:
    
    callable -
    
    Returns:
  - delayed
```
public void delayed(long millis,
                    Runnable toRun)
```
    schedule an action or call delayed. typical use case: delayed( 100, () -> { self().doAction( x, y, ); } );
  - isMailboxPressured
```
public boolean isMailboxPressured()
```
    WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
    
    Returns:
    
    true if mailbox fill size is ~half capacity
  - isEmpty
```
public boolean isEmpty()
```
  - getScheduler
```
public Scheduler getScheduler()
```
    Returns:
    
    the scheduler associated with this actor (determines scheduling of processing of actors to threads)
  - isCallbackQPressured
```
public boolean isCallbackQPressured()
```
    WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
    
    Returns:
    
    wether the callback queue is mor than half full (can indicate overload)
  - getMailboxSize
```
public int getMailboxSize()
```
    WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
    
    Returns:
    
    an estimation on the queued up entries in the mailbox. Can be used for bogus flow control
  - getQSizes
```
public int getQSizes()
```
    WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
    
    Returns:
    
    summed queue size of mailbox+callback queue
  - getCallbackSize
```
public int getCallbackSize()
```
    WARNING: call rarely, this method might have O(n) runtime with default unbounded queues.
    
    Returns:
    
    an estimation on the queued up callback entries. Can be used for bogus flow control.
  - inThread
```
protected <T> T inThread(Actor proxy,
                         T cbInterface)
```
    wraps an interface into a proxy of that interface. The proxy object automatically enqueues all calls made on the interface onto the callback queue. Can be used incase one needs to pass other callback interfaces then built in Callback object. Stick to using 'Callback' class if possible.
    
    Type Parameters:
    
    T -
    
    Parameters:
    
    proxy -
    
    cbInterface -
    
    Returns:
  - checkThread
```
protected final void checkThread()
```
    Debug method. can be called to check actor code is actually single threaded. By using custom callbacks/other threading bugs accidental multi threading can be detected that way.
  - getActorRef
```
public Actor getActorRef()
```
    Returns:
    
    the proxy of this actor
  - isRemote
```
public boolean isRemote()
```
    Returns:
    
    wether this is a proxy to a remotely running actor
  - close
```
public void close()
```
    closes associated remote connection(s) if present. NOP otherwise. Close refers to "unmapping" the serving actor, underlying network connections will be closed. All clients get disconnected
  - closeCurrentClient
```
protected void closeCurrentClient()
```
    closes the connection to the remote client which has sent currently executing message. If current message was not sent by a client, NOP.
  - asyncstop
```
public void asyncstop()
```
  - hasStopped
```
protected void hasStopped()
```
    override to clean up / stop dependend actors
  - stopSafeClose
```
public void stopSafeClose()
```
    avoids exception when closing an actor after stop has been called.
  - ping
```
public IPromise ping()
```
    can be used to wait for all messages having been processed and get a signal from the returned future once this is complete
    
    Returns:
  - serialOn
```
protected void serialOn(Object transactionKey,
                        Consumer<IPromise> toRun)
```
    enforce serial execution of asynchronous tasks. The 'toRun' closure must call '.complete()' (=empty result) on the given future to signal his processing has finished and the next item locked on 'transactionKey' can be processed.
    
    Parameters:
    
    transactionKey -
    
    toRun -
  - transferTo
```
public void transferTo(Actor target)
```
    only meaningful if this actor is a buffered actor (failover/reconnect scenarios). LIMITATION: not loss free in case. If new messages are enqueued from another thread while transfer is processed, messages can be lost. In case the buffering actor reference is replaced prior to calling transferTo(), message order might get messed up. However still useful on platforms which value availability over correctness. Note: In order to make this fully save, locking would be required at some point. As locking in central dispatch would result in a major performance bottleneck, so a special LockingScheduler or so could be implemented to support transactionally safe buffering actors. Due to time constraints, this might get implemented at some point in the future.
    
    Parameters:
    
    target -
  - setThrowExWhenBlocked
```
public SELF setThrowExWhenBlocked(boolean b)
```
    tellMsg the execution machinery to throw an ActorBlockedException in case the actor is blocked trying to put a message on an overloaded actor's mailbox/queue. Useful e.g. when dealing with actors representing a remote client (might block or lag due to connection issues). Obsolete since kontraktor defaults to unbounded queues
    
    Parameters:
    
    b -
    
    Returns:
  - getThrowExWhenBlocked
```
protected boolean getThrowExWhenBlocked()
```
  - isPublished
```
public boolean isPublished()
```
    Returns:
    
    true wether this actor is published to network
  - execute
```
public void execute(Runnable command)
```
    just enqueue given runable to this actors mailbox and execute on the actor's thread WARNING: the similar named method exec() works different (bad naming)
    
    Specified by:
    
    execute in interface Executor
    
    Parameters:
    
    command -
  - getCurrentDispatcher
```
public DispatcherThread getCurrentDispatcher()
```
  - getConnections
```
protected ConcurrentLinkedQueue<RemoteConnection> getConnections()
```
  - __addStopHandler
```
public void __addStopHandler(Callback<SELF> cb)
```
  - __addRemoteConnection
```
public void __addRemoteConnection(RemoteConnection con)
```
  - __removeRemoteConnection
```
public void __removeRemoteConnection(RemoteConnection con)
```
  - __stop
```
public void __stop()
```
  - __stopImpl
```
protected void __stopImpl()
```
  - __enqueueCall
```
public Object __enqueueCall(Actor receiver,
                            String methodName,
                            Object[] args,
                            boolean isCB)
```
  - __addDeadLetter
```
public void __addDeadLetter(Actor receiver,
                            String methodName)
```
  - __getCachedMethod
```
public Method __getCachedMethod(String methodName,
                                Actor actor,
                                BiFunction<Actor,String,Boolean> callInterceptor)
```
  - __dispatchRemoteCall
```
public boolean __dispatchRemoteCall(ObjectSocket objSocket,
                                    RemoteCallEntry rce,
                                    RemoteRegistry registry,
                                    List<IPromise> createdFutures,
                                    Object authContext,
                                    BiFunction<Actor,String,Boolean> callInterceptor)
```
    called if a message invokation from remote is received
    
    Returns:
    
    true if a new promise has been created
  - getReport
```
public IPromise getReport()
```
    Specified by:
    
    getReport in interface Monitorable
  - getSubMonitorables
```
public IPromise<Monitorable[]> getSubMonitorables()
```
    Specified by:
    
    getSubMonitorables in interface Monitorable

Class Actor<SELF extends Actor>

Nested Class Summary

Field Summary

Fields inherited from class org.nustaq.kontraktor.Actors

Constructor Summary

Method Summary

Methods inherited from class org.nustaq.kontraktor.Actors

Methods inherited from class java.lang.Object

Field Detail

sender

connection

__mailbox

__mbCapacity

__cbQueue

__currentDispatcher

__scheduler

__stopped

__self

__remoteId

__throwExAtBlock

__connections

__clientConnection

__mailboxCapacity

__ticketMachine

Constructor Detail

Actor

Method Detail

current

inside

__submit

self

getFactory

getActor

stop

isStopped

isProxy

askMsg

tellMsg

ask

tell

exec

delayed

isMailboxPressured

isEmpty

getScheduler

isCallbackQPressured

getMailboxSize

getQSizes

getCallbackSize

inThread

checkThread

getActorRef

isRemote

close

closeCurrentClient

asyncstop

hasStopped

stopSafeClose

ping

serialOn

transferTo

setThrowExWhenBlocked

getThrowExWhenBlocked

isPublished

execute

getCurrentDispatcher

getConnections

__addStopHandler

__addRemoteConnection

__removeRemoteConnection

__stop

__stopImpl

__enqueueCall

__addDeadLetter

__getCachedMethod

__dispatchRemoteCall

getReport

getSubMonitorables