Actor (kontraktor 3.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`
`int`	`__remoteId`
`Scheduler`	`__scheduler`
`Actor`	`__self`
`boolean`	`__stopped`
`boolean`	`__throwExAtBlock`
`protected TicketMachine`	`__ticketMachine`
`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_TIMOUT, defaultScheduler, delayedCalls, exec, FIN, FINSILENT, instance, MAX_EXTERNAL_THREADS_POOL_SIZE

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)`
`Object`	`__enqueueCall(Actor receiver, String methodName, Object[] args, boolean isCB)`
`Method`	`__getCachedMethod(String methodName, Actor actor)`
`void`	`__removeRemoteConnection(RemoteConnection con)`
`void`	`__stop()`
`void`	`__submit(Runnable toRun)`
`IPromise`	`ask(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.
`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
`SELF`	`getActor()`
`Actor`	`getActorRef()`
`int`	`getCallbackSize()`
`DispatcherThread`	`getCurrentDispatcher()`
`ActorProxyFactory`	`getFactory()`
`int`	`getMailboxSize()`
`int`	`getQSizes()`
`IPromise`	`getReport()`
`Scheduler`	`getScheduler()`
`IPromise<Monitorable[]>`	`getSubMonitorables()`
`protected boolean`	`getThrowExWhenBlocked()`
`static boolean`	`inside()`
`protected <T> T`	`inThread(Actor proxy, T cbInterface)` wraps an interface into a proxy of that interface.
`boolean`	`isCallbackQPressured()`
`boolean`	`isMailboxPressured()`
`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, java.util.function.Consumer<IPromise> toRun)` enforce serial execution of asynchronous tasks.
`SELF`	`setThrowExWhenBlocked(boolean b)` tell 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 messages.

Methods inherited from class org.nustaq.kontraktor.Actors
AddDeadLetter, all, all, AsActor, AsActor, AsActor, AsActor, awaitAll, awaitAll, awaitAll, awaitAll, complete, complete, DeadLetters, InThread, isCont, isError, isFinal, isResult, isSilentFinal, race, race, reject, resolve, resolve, stream, SubmitDelayed, yield, yield

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
  - __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 int __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.Channel(..) to construct actor instances
- Method Detail
  - current
```
public static Actor current()
```
    Returns:
    
    current actor thread 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
  - 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
  - ask
```
public IPromise ask(String messageId,
                    Object... args)
```
    generic method for untyped messages.
    
    Parameters:
    
    messageId -
    
    Returns:
  - tell
```
public void tell(String messageId,
                 Object... args)
```
    generic method for untyped messages.
    
    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).
    
    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()
```
    Returns:
    
    true if mailbox fill size is ~half capacity
  - getScheduler
```
public Scheduler getScheduler()
```
    Returns:
    
    the scheduler associated with this actor (determines scheduling of processing of actors to threads)
  - isCallbackQPressured
```
public boolean isCallbackQPressured()
```
    Returns:
    
    wether the callback queue is mor than half full (can indicate overload)
  - getMailboxSize
```
public int getMailboxSize()
```
    Returns:
    
    an estimation on the queued up entries in the mailbox. Can be used for bogus flow control
  - getQSizes
```
public int getQSizes()
```
    Returns:
    
    summed queue size of mailbox+callback queue
  - getCallbackSize
```
public int getCallbackSize()
```
    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. WARNING: only feasable when running in dev on single threaded scheduler (ElasticScheduler with a single thread), else false alarm might occur
  - 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.
  - asyncstop
```
public void asyncstop()
```
  - 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,
                        java.util.function.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 -
  - setThrowExWhenBlocked
```
public SELF setThrowExWhenBlocked(boolean b)
```
    tell 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).
    
    Parameters:
    
    b -
    
    Returns:
  - getThrowExWhenBlocked
```
protected boolean getThrowExWhenBlocked()
```
  - isPublished
```
public boolean isPublished()
```
  - __addStopHandler
```
public void __addStopHandler(Callback<SELF> cb)
```
  - __addRemoteConnection
```
public void __addRemoteConnection(RemoteConnection con)
```
  - __removeRemoteConnection
```
public void __removeRemoteConnection(RemoteConnection con)
```
  - __stop
```
public void __stop()
```
  - __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)
```
  - execute
```
public void execute(Runnable command)
```
    just enqueue given runable to this actors mailbox and execute on the actor's thread
    
    Specified by:
    
    execute in interface Executor
    
    Parameters:
    
    command -
  - getCurrentDispatcher
```
public DispatcherThread getCurrentDispatcher()
```
  - 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

__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

ask

tell

exec

delayed

isMailboxPressured

getScheduler

isCallbackQPressured

getMailboxSize

getQSizes

getCallbackSize

inThread

checkThread

getActorRef

isRemote

close

asyncstop

stopSafeClose

ping

serialOn

setThrowExWhenBlocked

getThrowExWhenBlocked

isPublished

__addStopHandler

__addRemoteConnection

__removeRemoteConnection

__stop

__enqueueCall

__addDeadLetter

__getCachedMethod

execute

getCurrentDispatcher

getReport

getSubMonitorables