coldbox.system.async

Class AsyncManager

lucee.Component
    extended by coldbox.system.async.AsyncManager

The ColdBox Async Manager is in charge of creating runnable proxies based on components or closures that can be spawned as native Java Completable futures to support you with multi-threaded and asynchronous programming. The manager can also help you create executor services (queues or work pools) so you can define your own thread pools according to your needs. If not, the majority of the asynchronous methods will use the ForkJoin.commonPool() implementation. Every ColdBox application has a single AsyncManager loaded with 1 work queue created mostly for internal ColdBox operations: `coldbox-tasks` with 20 threads. However, you can define as many executor pools in your configuration file and ColdBox will manage them for you via this Async Manager. Welcome to the world of async and parallel programming!

Class Attributes:
  • singleton
    •  
  • synchronized : false
    •  
  • accessors : true
    •  
  • persistent : false
    •  
    Property Summary
    type property default serializable required
    any coldbox
          This scheduler can be linked to a ColdBox context.

    • access = public
    • returntype = any
    		 true false
    struct executors
          A collection of executors you can register in the async manager.

    • access = public
    • returntype = any
    		 true false
    Constructor Summary
    init([boolean debug='false'])
          Constructor.
    Method Summary
    coldbox.system.async.Future all()
         Alias to newFuture().
    any allApply()
         Alias to newFuture().
    coldbox.system.async.Future anyOf()
         Alias to newFuture().
    array arrayRange([any from='1'], [numeric to])
         Build an array out of a range of numbers or using our range syntax.
    private any buildExecutor(any type, [numeric threads], [boolean debug='false'], [boolean loadAppContext='true'])
         Build a Java executor according to passed type and threads.
    AsyncManager deleteExecutor(any name)
         Delete an executor from the registry, if the executor has not shutdown, it will shutdown the executor for you.
    coldbox.system.async.Duration duration()
         Build out a new Duration class.
    AsyncManager err(any var)
         Utility to send to output to the error stream.
    string getColdbox()
    coldbox.system.async.Executor getExecutor(any name)
         Get a registered executor registered in this async manager.
    array getExecutorNames()
         Get the array of registered executors in the system.
    struct getExecutorStatusMap([any name])
         Returns a structure of status maps for every registered executor in the.
    string getExecutors()
    boolean hasExecutor(any name)
         Verify if an executor exists.
    coldbox.system.async.Executor newCachedExecutor(any name, [numeric threads='[runtime expression]'], [boolean debug='false'], [boolean loadAppContext='true'])
         Shortcut to newExecutor( type: "cached" ).
    coldbox.system.async.Future newCompletedFuture(any value, [boolean debug='false'], [boolean loadAppContext='true'])
         Create a completed ColdBox future backed by a Java Completable Future.
    coldbox.system.async.Executor newExecutor(any name, [any type='fixed'], [numeric threads='[runtime expression]'], [boolean debug='false'], [boolean loadAppContext='true'])
         Creates and registers an Executor according to the passed name, type and options.
    coldbox.system.async.Future newFuture([any value], [any executor], [boolean debug='false'], [boolean loadAppContext='true'])
         Create a new ColdBox future backed by a Java completable future.
    coldbox.system.async.Executor newScheduledExecutor(any name, [numeric threads='[runtime expression]'], [boolean debug='false'], [boolean loadAppContext='true'])
         Shortcut to newExecutor( type: "scheduled" ).
    coldbox.system.async.Scheduler newScheduler(any name)
         Build out a scheduler object for usage within this async manager context and return it to you.
    coldbox.system.async.Executor newSingleExecutor(any name, [boolean debug='false'], [boolean loadAppContext='true'])
         Shortcut to newExecutor( type: "single", threads: 1 ).
    AsyncManager out(any var)
         Utility to send to output to the output stream.
    coldbox.system.async.Period period()
         Build out a new Period class.
    any setColdbox(any coldbox)
    any setExecutors(struct executors)
    AsyncManager shutdownAllExecutors([boolean force='false'])
         Shutdown all registered executors in the system.
    AsyncManager shutdownExecutor(any name, [boolean force='false'])
         Shutdown an executor or force it to shutdown, you can also do this from the Executor themselves.
     
    Methods inherited from class lucee.Component
    None
    Constructor Detail

    init

    public init([boolean debug='false'])

    Constructor

    Parameters:
    debug - Add debugging logs to System out, disabled by default
    Property Detail

    coldbox

    property any coldbox

    This scheduler can be linked to a ColdBox context

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    executors

    property struct executors

    A collection of executors you can register in the async manager so you can run queues, tasks or even scheduled tasks

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true
    Method Detail

    all

    public coldbox.system.async.Future all()

    Alias to newFuture().all()

    allApply

    public any allApply()

    Alias to newFuture().allApply()

    anyOf

    public coldbox.system.async.Future anyOf()

    Alias to newFuture().anyOf()

    arrayRange

    public array arrayRange([any from='1'], [numeric to])

    Build an array out of a range of numbers or using our range syntax. You can also build negative ranges 

    arrayRange( "1..5" )
arrayRange( "-10..5" )
arrayRange( 1, 500 )

    Parameters:
    from - The initial index, defaults to 1 or you can use the {start}..{end} notation
    to - The last index item

    buildExecutor

    private any buildExecutor(any type, [numeric threads], [boolean debug='false'], [boolean loadAppContext='true'])

    Build a Java executor according to passed type and threads

    Parameters:
    type - Available types are: fixed, cached, single, scheduled, {WireBoxID}
    threads - The number of threads to seed the executor with, if it allows it
    debug - Add output debugging
    loadAppContext - Load the CFML App contexts or not, disable if not used
    Returns:
    A Java ExecutorService: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

    deleteExecutor

    public AsyncManager deleteExecutor(any name)

    Delete an executor from the registry, if the executor has not shutdown, it will shutdown the executor for you using the shutdownNow() event

    Parameters:
    name - The scheduler name

    duration

    public coldbox.system.async.Duration duration()

    Build out a new Duration class

    err

    public AsyncManager err(any var)

    Utility to send to output to the error stream

    Parameters:
    var - Variable/Message to send

    getColdbox

    public string getColdbox()

    getExecutor

    public coldbox.system.async.Executor getExecutor(any name)

    Get a registered executor registered in this async manager

    Parameters:
    name - The executor name
    Returns:
    The executor object: coldbox.system.async.executors.Executor
    Throws:
    ExecutorNotFoundException

    getExecutorNames

    public array getExecutorNames()

    Get the array of registered executors in the system

    Returns:
    Array of names

    getExecutorStatusMap

    public struct getExecutorStatusMap([any name])

    Returns a structure of status maps for every registered executor in the manager. This is composed of tons of stats about the executor

    Parameters:
    name - The name of the executor to retrieve th status map ONLY!
    Returns:
    A struct of metadata about the executor or all executors

    getExecutors

    public string getExecutors()

    hasExecutor

    public boolean hasExecutor(any name)

    Verify if an executor exists

    Parameters:
    name - The executor name

    newCachedExecutor

    public coldbox.system.async.Executor newCachedExecutor(any name, [numeric threads='[runtime expression]'], [boolean debug='false'], [boolean loadAppContext='true'])

    Shortcut to newExecutor( type: "cached" )

    Parameters:
    name
    threads
    debug
    loadAppContext

    newCompletedFuture

    public coldbox.system.async.Future newCompletedFuture(any value, [boolean debug='false'], [boolean loadAppContext='true'])

    Create a completed ColdBox future backed by a Java Completable Future

    Parameters:
    value - The value to complete the future with
    debug - Add debugging to system out or not, defaults is false
    loadAppContext - Load the CFML engine context into the async threads or not, default is yes.
    Returns:
    ColdBox Future completed

    newExecutor

    public coldbox.system.async.Executor newExecutor(any name, [any type='fixed'], [numeric threads='[runtime expression]'], [boolean debug='false'], [boolean loadAppContext='true'])

    Creates and registers an Executor according to the passed name, type and options. The allowed types are: fixed, cached, single, scheduled with fixed being the default. You can then use this executor object to submit tasks for execution and if it's a scheduled executor then actually execute scheduled tasks. Types of Executors: - fixed : By default it will build one with 20 threads on it. Great for multiple task execution and worker processing - single : A great way to control that submitted tasks will execute in the order of submission: FIFO - cached : An unbounded pool where the number of threads will grow according to the tasks it needs to service. The threads are killed by a default 60 second timeout if not used and the pool shrinks back - scheduled : A pool to use for scheduled tasks that can run one time or periodically

    Parameters:
    name - The name of the executor used for registration
    type - The type of executor to build fixed, cached, single, scheduled
    threads - How many threads to assign to the thread scheduler, default is 20
    debug - Add output debugging
    loadAppContext - Load the CFML App contexts or not, disable if not used
    Returns:
    The ColdBox Schedule class to work with the schedule: coldbox.system.async.executors.Executor

    newFuture

    public coldbox.system.async.Future newFuture([any value], [any executor], [boolean debug='false'], [boolean loadAppContext='true'])

    Create a new ColdBox future backed by a Java completable future

    Parameters:
    value - The actual closure/lambda/udf to run with or a completed value to seed the future with
    executor - A custom executor to use with the future, else use the default
    debug - Add debugging to system out or not, defaults is false
    loadAppContext - Load the CFML engine context into the async threads or not, default is yes.
    Returns:
    ColdBox Future completed or new

    newScheduledExecutor

    public coldbox.system.async.Executor newScheduledExecutor(any name, [numeric threads='[runtime expression]'], [boolean debug='false'], [boolean loadAppContext='true'])

    Shortcut to newExecutor( type: "scheduled" )

    Parameters:
    name
    threads
    debug
    loadAppContext

    newScheduler

    public coldbox.system.async.Scheduler newScheduler(any name)

    Build out a scheduler object for usage within this async manager context and return it to you. You must manage it's persistence, we only wire it and create it for you so you can use it to schedule tasks.

    Parameters:
    name - The unique name for the scheduler

    newSingleExecutor

    public coldbox.system.async.Executor newSingleExecutor(any name, [boolean debug='false'], [boolean loadAppContext='true'])

    Shortcut to newExecutor( type: "single", threads: 1 )

    Parameters:
    name
    debug
    loadAppContext

    out

    public AsyncManager out(any var)

    Utility to send to output to the output stream

    Parameters:
    var - Variable/Message to send

    period

    public coldbox.system.async.Period period()

    Build out a new Period class

    setColdbox

    public any setColdbox(any coldbox)

    Parameters:
    coldbox

    setExecutors

    public any setExecutors(struct executors)

    Parameters:
    executors

    shutdownAllExecutors

    public AsyncManager shutdownAllExecutors([boolean force='false'])

    Shutdown all registered executors in the system

    Parameters:
    force - By default (false) it gracefully shuts them down, else uses the shutdownNow() methods
    Returns:
    AsyncManager

    shutdownExecutor

    public AsyncManager shutdownExecutor(any name, [boolean force='false'])

    Shutdown an executor or force it to shutdown, you can also do this from the Executor themselves. If an un-registered executor name is passed, it will ignore it

    Parameters:
    name
    force - Use the shutdownNow() instead of the shutdown() method