com.ebay.bascomtask.main

Class Orchestrator

java.lang.Object

com.ebay.bascomtask.main.Orchestrator

public class Orchestrator
extends Object

A dataflow-driven collector and executor of tasks that implicitly honors all dependencies while pursuing maximum parallelization with a minimum number of threads.

A task can be any POJO which can have any number of @Work or @PassThru annotated methods, which we refer to as task methods. Once added, execute() will execute those methods either if they have no arguments or once those arguments become available as a result of executing other tasks. A task method's arguments will never be null, so no null checks are required in task methods. For any POJO added as a task, either its @Work or its @PassThru method(s) will be executed (never both), depending on whether it was added by addWork(Object) or by addPassThru(Object). @PassThru is intended for use when a task needs to do only simple bookkeeping but otherwise is not actively contributing to the overall result. Typically a given POJO will have just one @Work and possibly one @PassThru method, but can have any number of these; at runtime, whichever method matches based on available inputs will fire (execute).

An example pojo invoked with BascomTask might be as follows:

 class MyTask {
   @Work void exec(MyOtherTask x, SomeOtherTask y) {...}
 }
 Orchestrator orc = Orchestrator.create();
 orc.addWork(new new MyTask());
 orc.addWork(new new MyOtherTask());
 orc.addWork(new new SomeOtherTask());
 orc.execute();
 

If MyOtherTask and SomOtherTask have no common dependencies then they may be executed in parallel in different threads. BascomTask is dataflow driven, attempting to execute tasks in parallel where possible while avoiding wasteful creation of threads where possible.

Multiple instances of a given POJO class can also be added, each being executed separately and each being supplied to all downstream task methods with that type as an argument. If two instances of MyOtherTask were added to the previous example, each would start in its own thread and MyTask.exec() would be invoked twice, each time with a different MyOtherTask instance. The default behavior for a task that receives multiple calls is simply to allow them to proceed independently each firing in turn to any downstream tasks. This assumes that the task (MyTask in the above example) is thread-safe. There are several options for varying this behavior by adding a scope argument to @Work, see Scope for a description of options. Even simpler is to simply change a task argument to a list, in which case all instances of that type will be received at once.

Author:

brendanmccarthy

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Orchestrator.ExecutionStats

Method Summary

Methods

Modifier and Type	Method and Description
ITask	addConditionally(Object task, boolean cond) A convenience method, adds a task with a default name that is either active or passive depending on the given condition.
ITask	addIgnoreTaskMethods(Object task) Adds an object without considering any @Work or @PassThru methods even if they exist, as if the object did not have such methods in the first place.
ITask	addPassThru(Object task) Adds a task whose @PassThru methods (rather than its @@Work methods) will be invoked, always in the calling thread -- no separate thread is created to execute a @PassThru method since it assumed to perform simple actions like providing a default or passing-through its arguments with no or little change.
ITask	addWork(Object task) Adds a task to be made available to other task's task (@Work or @PassThru) methods, and whose own @Work methods will only be invoked (fired) when its task arguments have so fired.
ITask	asAdded(Object targetTask) Returns the ITask wrapper for a POJO task that has already been added to this orchestrator
Orchestrator	closureGenerator(ITaskClosureGenerator generator) Sets a closure generator to use for this orchestrator, rather than the default which is retrieved from whichever IBascomConfig is active.
static Orchestrator	create()
void	execute() Calls execute(long) with a default from current IBascomConfig.getDefaultOrchestratorTimeoutMs()
void	execute(long maxExecutionTimeMillis)
void	execute(long maxExecutionTimeMillis, String pass) Begins processing of previously added tasks within the calling thread, spawning new threads where possible to exploit parallel execution and returning when all no-wait tasks are finished.
void	execute(String pass)
String	getGraphState() Returns a newline-separated list of all calls of all tasks.
String	getId() Returns an id for this instance which has very low probability of clashing with other ids.
String	getName() The name previously set by name(String)
Orchestrator.ExecutionStats	getNoWaitStats() Returns a snapshot of execution statistics resulting from a previous execution, including any nowait tasks.
int	getNumberOfOpenThreads() Returns the number of threads that have been spawned but not yet completed.
int	getNumberOfThreadsCreated() Returns the number of additional threads (not including the starting thread) used in computing the result from this orchestrator.
Orchestrator.ExecutionStats	getStats() Returns a snapshot of execution statistics resulting from a previous execution, excluding any nowait tasks.
TaskThreadStat	getThreadStatForCurrentThread()
Orchestrator	name(String name) Sets a name used on entry and exit debugging statements, useful for identify which orchestrator is being invoked when there are many involved.
void	recordException(com.ebay.bascomtask.main.Call.Instance callInstance, Exception e)
void	recordException(Exception e)
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

toString

public String toString()

Overrides:

toString in class Object

create

public static Orchestrator create()

getStats

public Orchestrator.ExecutionStats getStats()

Returns a snapshot of execution statistics resulting from a previous execution, excluding any nowait tasks. This method is guaranteed to return the same result once the outermost execute() has completed.

Returns:

stats snapshot

getNoWaitStats

public Orchestrator.ExecutionStats getNoWaitStats()

Returns a snapshot of execution statistics resulting from a previous execution, including any nowait tasks. This method is guaranteed to return the same result once the outermost execute() has completed and all nowait tasks have completed.

Returns:

stats snapshot

name

public Orchestrator name(String name)

Sets a name used on entry and exit debugging statements, useful for identify which orchestrator is being invoked when there are many involved.

Parameters:

name - to include in debug statements

Returns:

this instance for fluent-style chaining

getName

public String getName()

The name previously set by name(String)

Returns:

the name or null if not previously set

getId

public String getId()

Returns an id for this instance which has very low probability of clashing with other ids.

Returns:

id of this object

closureGenerator

public Orchestrator closureGenerator(ITaskClosureGenerator generator)

Sets a closure generator to use for this orchestrator, rather than the default which is retrieved from whichever IBascomConfig is active.

Parameters:

generator - to use in place of default

Returns:

this instance for fluent-style chaining

See Also:

IBascomConfig.getExecutionHook(Orchestrator, String)

getThreadStatForCurrentThread

public TaskThreadStat getThreadStatForCurrentThread()

getNumberOfThreadsCreated

public int getNumberOfThreadsCreated()

Returns the number of additional threads (not including the starting thread) used in computing the result from this orchestrator. The value may increase until all tasks are terminated.

Returns:

count of created threads

getNumberOfOpenThreads

public int getNumberOfOpenThreads()

Returns the number of threads that have been spawned but not yet completed. The returned value may only be > 0 after a call to execute() if there are nowait tasks.

Returns:

number of open threads

addConditionally

public ITask addConditionally(Object task,
                     boolean cond)

A convenience method, adds a task with a default name that is either active or passive depending on the given condition.

Parameters:

task - java POJO to add as task

cond - if true then add as active else add as passive

Returns:

a 'shadow' task object which allows for various customizations

addWork

public ITask addWork(Object task)

Adds a task to be made available to other task's task (@Work or @PassThru) methods, and whose own @Work methods will only be invoked (fired) when its task arguments have so fired.

The rules for execution are as follows:

• A POJO can have no @Work methods in which case it will instantly be available to other tasks.
• Any @Work method with no arguments will be started immediately in its own thread (which might be the calling thread of the orchestrator if it is not busy with other work).
• Any Work method with arguments will only be invoked when all of its task parameters have themselves completed with a proper return (see last point below).
• Each @Work method will be invoked with the cross-product of all available matching instances.

Regarding the last point, although it is common to add just one instance of a given POJO type, it is safe to add any number. The default behavior of @Work methods receiving argument sequences with multiple instances is that each is executed potentially in parallel. Different options can be set through @Work.scope, see Scope. Alternatively, a @{literal @}Work method parameter can simply be a List of tasks in which case the entire set of matching instances will be made available once all instances are available.

An added task will have no effect until execute(long) is called, either directly or implicitly as a result of a nested task method completing.

A @Work can return a boolean result or simply be void, which equates to returning true. A return value of false indicates that downstream tasks should not fire: any task fires only if all of its inputs have fired, except for List parameters, which never prevent firing but instead any false-returning tasks will be excluded from the list (which means that a list parameter may be empty).

Parameters:

task - java POJO to add as task

Returns:

a 'shadow' task object which allows for various customizations

addPassThru

public ITask addPassThru(Object task)

Adds a task whose @PassThru methods (rather than its @@Work methods) will be invoked, always in the calling thread -- no separate thread is created to execute a @PassThru method since it assumed to perform simple actions like providing a default or passing-through its arguments with no or little change. Otherwise behaves the same as addWork(Object).

Parameters:

task - java POJO to add as task

Returns:

a 'shadow' task object which allows for various customizations

addIgnoreTaskMethods

public ITask addIgnoreTaskMethods(Object task)

Adds an object without considering any @Work or @PassThru methods even if they exist, as if the object did not have such methods in the first place. This enables the object to be make available as a parameter to other task methods without the object's task methods firing. Usage of this method is relatively uncommon, but does provide another way to handle variant situations be allowing a task object to be exposed but have its behavior managed outside the scope of an orchestrator.

Parameters:

task - to add

Returns:

a 'shadow' task object which allows for various customizations

asAdded

public ITask asAdded(Object targetTask)

Returns the ITask wrapper for a POJO task that has already been added to this orchestrator

Parameters:

targetTask - to match

Returns:

ITask for previously added POJO or null if no such POJO was ever added

recordException

public void recordException(com.ebay.bascomtask.main.Call.Instance callInstance,
                   Exception e)

recordException

public void recordException(Exception e)

execute

public void execute()

Calls execute(long) with a default from current IBascomConfig.getDefaultOrchestratorTimeoutMs()

execute

public void execute(String pass)

execute

public void execute(long maxExecutionTimeMillis)

execute

public void execute(long maxExecutionTimeMillis,
           String pass)

Begins processing of previously added tasks within the calling thread, spawning new threads where possible to exploit parallel execution and returning when all no-wait tasks are finished. Any task will hold up the exit of this method when all of the following apply:

1. It has not been flagged as no-wait
2. It has at least one @Work (or @PassThru) method
3. All of its methods that can fire (because there are matching instances as parameters) have fired
4. It has at least one such fireable method that may fire again

This method can safely be called multiple times, each time accounting for any new tasks added and firing all tasks that are fireable as a result of those new tasks added. In this way, each call to execute acts like a synchronizer across all executable tasks. Tasks added within a nested task can but do not have to call execute() if they add tasks, as there is an implicit call done automatically in this case. Note that tasks added by other threads will be invisible to the calling thread.

Consistency checks are performed prior to any task being started, and if a violation is found a subclass of InvalidGraph is thrown.

If any task throws an exception, which would have to be a non-checked exception, it will be propagated from this call. Once such an exception is thrown, the orchestrator ceases to start new tasks and instead waits for all open threads to finish before returning (by throwing the exception in question).

Parameters:

maxExecutionTimeMillis - to timeout

pass - description passed to config executors

Throws:

RuntimeException - generated from a task

RuntimeGraphError.Timeout - when the requested timeout has been exceeded

RuntimeGraphError.Multi - if more than one exception is thrown from different tasks

InvalidTask.AlreadyAdded - if the same task instance was added more than once

InvalidTask.BadParam - if a task method has a parameter that cannot be processed

InvalidGraph.MissingDependents - if a task cannot be exited because it has no matching @Work dependents

InvalidGraph.Circular - if a circular reference between two tasks is detected

InvalidGraph.MultiMethod - if a task has more than one callable method and is not marked multiMethodOk()

InvalidGraph.ViolatedProvides - if a task was indicated to ITask.provides(Class) an instance but this was not done (or @PassThru) method that has all of its parameters available as instances

getGraphState

public String getGraphState()

Returns a newline-separated list of all calls of all tasks.

Returns:

multi-line graph state summary