Actor (kontraktor 2.00 API)

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

All Implemented Interfaces:

Serializable, Monitorable

Direct Known Subclasses:

HttpMonitor, Log, NioHttpServerImpl
```
public class Actor<SELF extends Actor>
extends Object
implements Serializable, Monitorable
```
Baseclass for actor implementations. Note that actors are not created using constructors. Use Actors.AsActor(..) or Actor.SpawnActor() to instantiate an actor instance. To pass initialization parameter, define an init method in your implementation and call it from the instantiating instance. e.g.; MyActor act = Actors.Channel(MyActor.class); act.myInit( x,y,z ); The init method then will be executed in the thread of the dispatcher associated with your actor avoiding problems rised by state visibility inconsistency amongst threads. Inside an actor, everything is executed single threaded. You don't have to worry about synchronization. All 'messages' of an actor are defined by 'public void' methods. Actor methods are not allowed to return values. They must be of type void. Pass a Callback as argument to a call in order to receive results from other actors/threads. Non public methods can be called from inside the actor, but not outside as a message. Note that you have to pass immutable objects as arguments, else you'll get unpredictable behaviour. Code inside an actor is not allowed to ever block the current thread (networking etc.). Use Actors.Exec in case you need to do blocking calls (e.g. synchronous requests)

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`
`ConcurrentLinkedQueue<RemoteConnection>`	`__connections`
`Thread`	`__currentDispatcher`
`Queue`	`__mailbox`
`int`	`__mbCapacity`
`int`	`__remoteId`
`Scheduler`	`__scheduler`
`Actor`	`__self`
`boolean`	`__stopped`
`boolean`	`__throwExAtBlock`
`protected TicketMachine`	`__ticketMachine`
`static String`	`CONT` use value as error to indicate more messages are to come (else remoting will close channel).
`static String`	`FIN` use this value to signal no more messages.
`static String`	`FINSILENT` use value to signal no more messages.
`static ThreadLocal<Actor>`	`sender`

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`	`$close()` closes associated remote connection(s) if present.
`Future`	`$getReport()`
`Future<Monitorable[]>`	`$getSubMonitorables()`
`void`	`$stop()` $$stop receiving events.
`Future`	`$sync()` can be used to wait for all messages having been processed
`protected void`	`checkThread()` Debug method.
`protected void`	`delayed(long millis, Runnable toRun)` schedule an action or call delayed.
`protected <T> Future<T>`	`exec(Callable<T> callable)` execute a callable asynchronously (in a different thread) and return a future of the result (delivered in caller thread) WARNING: do not access local actor state (instance fields) from within the callable (=hidden parallelism).
`SELF`	`getActor()`
`Actor`	`getActorRef()`
`int`	`getCallbackSize()`
`ActorProxyFactory`	`getFactory()`
`int`	`getMailboxSize()`
`int`	`getQSizes()`
`Scheduler`	`getScheduler()`
`protected boolean`	`getThrowExWhenBlocked()`
`protected <T> T`	`inThread(Actor proxy, T cbInterface)`
`boolean`	`isCallbackQPressured()`
`static boolean`	`isCont(Object o)`
`static boolean`	`isError(Object o)`
`static boolean`	`isFinal(Object error)` return if given error Object signals end of callback stream
`boolean`	`isMailboxPressured()`
`boolean`	`isProxy()`
`boolean`	`isRemote()`
`static boolean`	`isSilentFinal(Object o)`
`boolean`	`isStopped()`
`protected Future<Future[]>`	`ordered(Callable<Future>... callables)` execute given callables asynchronously, but one after another async but chained.
`protected void`	`run(Runnable toRun)` execute a callable asynchronously (in a different thread) and return a future of the result (delivered in caller thread).
`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<Future> toRun)` enforce serial execution of asynchronous tasks.
`protected 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`	`stopSafeClose()` avoids exception when closing an actor after stop has been called.
`protected Future<Future[]>`	`yield(Future... futures)`
`protected <T> Future<T[]>`	`yield2Result(Future<T>... futures)` same as yield, but converts the resulting Future[] to an Object[] or T[]
`protected Future<List<Future>>`	`yieldList(List<Future> futures)`

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

- Field Detail
  - FINSILENT
```
public static final String FINSILENT
```
    use value to signal no more messages. THE RECEIVER CALLBACK WILL NOT SEE THIS MESSAGE.
    
    See Also:
    
    Constant Field Values
  - CONT
```
public static final String CONT
```
    use value as error to indicate more messages are to come (else remoting will close channel).
    
    See Also:
    
    Constant Field Values
  - FIN
```
public static final String FIN
```
    use this value to signal no more messages. The receiver callback will receive the message. Note that any value except CONT will also close the callback channel. So this is informal.
    
    See Also:
    
    Constant Field Values
  - sender
```
public static ThreadLocal<Actor> sender
```
  - __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
```
  - __ticketMachine
```
protected TicketMachine __ticketMachine
```
- Constructor Detail
  - Actor
```
public Actor()
```
    required by bytecode magic. Use Actors.Channel(..) to construct actor instances
- Method Detail
  - isFinal
```
public static boolean isFinal(Object error)
```
    return if given error Object signals end of callback stream
    
    Parameters:
    
    error -
    
    Returns:
  - isSilentFinal
```
public static boolean isSilentFinal(Object o)
```
  - isCont
```
public static boolean isCont(Object o)
```
  - isError
```
public static boolean isError(Object o)
```
  - 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()
```
  - isProxy
```
public boolean isProxy()
```
  - yield
```
protected Future<Future[]> yield(Future... futures)
```
  - yield2Result
```
protected <T> Future<T[]> yield2Result(Future<T>... futures)
```
    same as yield, but converts the resulting Future[] to an Object[] or T[]
    
    Parameters:
    
    futures -
    
    Returns:
  - ordered
```
protected Future<Future[]> ordered(Callable<Future>... callables)
```
    execute given callables asynchronously, but one after another async but chained. see https://gist.github.com/RuedigerMoeller/10c583819616f2563969
    
    Parameters:
    
    callables -
    
    Returns:
  - yieldList
```
protected Future<List<Future>> yieldList(List<Future> futures)
```
  - exec
```
protected <T> Future<T> exec(Callable<T> callable)
```
    execute a callable asynchronously (in a different thread) and return a future of the result (delivered in caller thread) WARNING: do not access local actor state (instance fields) from within the callable (=hidden parallelism).
    
    Type Parameters:
    
    T -
    
    Parameters:
    
    callable -
    
    Returns:
  - run
```
protected void run(Runnable toRun)
```
    execute a callable asynchronously (in a different thread) and return a future of the result (delivered in caller thread). WARNING: do not access local actor state (instance fields) from within the runnable (=hidden parallelism).
  - inThread
```
protected <T> T inThread(Actor proxy,
                         T cbInterface)
```
  - delayed
```
protected 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()
```
  - isCallbackQPressured
```
public boolean isCallbackQPressured()
```
  - 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()
```
  - getCallbackSize
```
public int getCallbackSize()
```
    Returns:
    
    an estimation on the queued up callback entries. Can be used for bogus flow control.
  - 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()
```
  - isRemote
```
public boolean isRemote()
```
  - $close
```
public void $close()
```
    closes associated remote connection(s) if present. NOP otherwise.
  - stopSafeClose
```
public void stopSafeClose()
```
    avoids exception when closing an actor after stop has been called.
  - $sync
```
public Future $sync()
```
    can be used to wait for all messages having been processed
    
    Returns:
  - __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)
```
  - serialOn
```
protected void serialOn(Object transactionKey,
                        java.util.function.Consumer<Future> toRun)
```
    enforce serial execution of asynchronous tasks. The 'toRun' closure must call '.signal()' on the given future to signal his processing has finished and the next item locked on 'transactionKey' can be processed.
    
    Parameters:
    
    transactionKey -
    
    toRun -
  - setThrowExWhenBlocked
```
protected 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()
```
  - $getReport
```
public Future $getReport()
```
    Specified by:
    
    $getReport in interface Monitorable
  - $getSubMonitorables
```
public Future<Monitorable[]> $getSubMonitorables()
```
    Specified by:
    
    $getSubMonitorables in interface Monitorable

Class Actor<SELF extends Actor>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FINSILENT

CONT

FIN

sender

__mailbox

__mbCapacity

__cbQueue

__currentDispatcher

__scheduler

__stopped

__self

__remoteId

__throwExAtBlock

__connections

__ticketMachine

Constructor Detail

Actor

Method Detail

isFinal

isSilentFinal

isCont

isError

self

getFactory

getActor

$stop

isStopped

isProxy

yield

yield2Result

ordered

yieldList

exec

run

inThread

delayed

isMailboxPressured

getScheduler

isCallbackQPressured

getMailboxSize

getQSizes

getCallbackSize

checkThread

getActorRef

isRemote

$close

stopSafeClose

$sync

__addStopHandler

__addRemoteConnection

__removeRemoteConnection

__stop

__enqueueCall

__addDeadLetter

__getCachedMethod

serialOn

setThrowExWhenBlocked

getThrowExWhenBlocked

$getReport

$getSubMonitorables