decaf::util::concurrent::ExecutorService Class Reference

An Executor that provides methods to manage termination and methods that can produce a Future for tracking progress of one or more asynchronous tasks. More...

#include <src/main/decaf/util/concurrent/ExecutorService.h>

Inheritance diagram for decaf::util::concurrent::ExecutorService:

[legend]

Public Member Functions
virtual	~ExecutorService ()
virtual bool	awaitTermination (long long timeout, const TimeUnit &unit)=0
	The caller will block until the executor has completed termination meaning all tasks that where scheduled before shutdown have now completed and the executor is ready for deletion.
virtual void	shutdown ()=0
	Performs an orderly shutdown of this Executor.
virtual ArrayList < decaf::lang::Runnable * >	shutdownNow ()=0
	Attempts to stop all currently executing tasks and returns an ArrayList containing the Runnables that did not get executed, these object become the property of the caller and are not deleted by this class, they are removed from the work queue and forgotten about.
virtual bool	isShutdown () const =0
	Returns whether this executor has been shutdown or not.
virtual bool	isTerminated () const =0
	Returns whether all tasks have completed after this executor was shut down.
template<typename E >
Future< E > *	submit (Callable< E > *task, bool takeOwnership=true)
	Submits a value-returning task for execution and returns a Future pointer representing the pending results of the task.
template<typename E >
Future< E > *	submit (decaf::lang::Runnable *task, const E &result, bool takeOwnership=true)
	Submits a Runnable task for execution and returns a Future representing that task.
template<typename E >
Future< E > *	submit (decaf::lang::Runnable *task, bool takeOwnership=true)
	Submits a Runnable object for execution.
Protected Member Functions
virtual void	doSubmit (FutureType *future)=0
	Perform the actual submit of a FutureType instance, the caller is responsible for creating the properly typed Future<E> object and returning that to its caller.

---

Detailed Description

An Executor that provides methods to manage termination and methods that can produce a Future for tracking progress of one or more asynchronous tasks.

An ExecutorService can be shut down, which will cause it to reject new tasks. Two different methods are provided for shutting down an ExecutorService. The shutdown() method will allow previously submitted tasks to execute before terminating, while the shutdownNow() method prevents waiting tasks from starting and attempts to stop currently executing tasks. Upon termination, an executor has no tasks actively executing, no tasks awaiting execution, and no new tasks can be submitted. An unused ExecutorService should be shut down to allow reclamation of its resources.

Method submit extends base method Executor.execute(decaf.lang.Runnable) by creating and returning a Future that can be used to cancel execution and/or wait for completion. Methods invokeAny and invokeAll perform the most commonly useful forms of bulk execution, executing a collection of tasks and then waiting for at least one, or all, to complete. (Class ExecutorCompletionService can be used to write customized variants of these methods.)

The Executors class provides factory methods for the executor services provided in this package.

Since:

1.0

---

Constructor & Destructor Documentation

virtual decaf::util::concurrent::ExecutorService::~ExecutorService

(

)

[inline, virtual]

---

Member Function Documentation

virtual bool decaf::util::concurrent::ExecutorService::awaitTermination	(	long long	timeout,
		const TimeUnit &	unit
	)			[pure virtual]

The caller will block until the executor has completed termination meaning all tasks that where scheduled before shutdown have now completed and the executor is ready for deletion.

If the timeout period elapses before the executor reaches the terminated state then this method return false to indicate it has not terminated.

Parameters:

	timeout	The amount of time to wait before abandoning the wait for termination.
	unit	The unit of time that the timeout value represents.

Returns:

true if the executor terminated or false if the timeout expired.

Exceptions:

InterruptedException

if this call is interrupted while awaiting termination.

Implemented in decaf::util::concurrent::ThreadPoolExecutor.

virtual void decaf::util::concurrent::ExecutorService::doSubmit

(

FutureType *

future

)

[protected, pure virtual]

Perform the actual submit of a FutureType instance, the caller is responsible for creating the properly typed Future<E> object and returning that to its caller.

The pointer provided is the property of this Executor and must be deleted by this executor once its completed.

Parameters:

future

Pointer to a base FutureType instance that is to be submitted to the Executor.

Implemented in decaf::util::concurrent::AbstractExecutorService.

virtual bool decaf::util::concurrent::ExecutorService::isShutdown

(

)

const [pure virtual]

Returns whether this executor has been shutdown or not.

Returns:

true if this executor has been shutdown.

Implemented in decaf::util::concurrent::ThreadPoolExecutor.

virtual bool decaf::util::concurrent::ExecutorService::isTerminated

(

)

const [pure virtual]

Returns whether all tasks have completed after this executor was shut down.

Returns:

true if all tasks have completed after a request to shut down was made.

Implemented in decaf::util::concurrent::ThreadPoolExecutor.

virtual void decaf::util::concurrent::ExecutorService::shutdown

(

)

[pure virtual]

Performs an orderly shutdown of this Executor.

Previously queued tasks are allowed to complete but no new tasks are accepted for execution. Calling this method more than once has no affect on this executor.

Implemented in decaf::util::concurrent::ThreadPoolExecutor.

virtual ArrayList<decaf::lang::Runnable*> decaf::util::concurrent::ExecutorService::shutdownNow

(

)

[pure virtual]

Attempts to stop all currently executing tasks and returns an ArrayList containing the Runnables that did not get executed, these object become the property of the caller and are not deleted by this class, they are removed from the work queue and forgotten about.

There is no guarantee that this method will halt execution of currently executing tasks.

Returns:

an ArrayList containing all Runnable instance that were still waiting to be executed by this class, call now owns those pointers.

Implemented in decaf::util::concurrent::ThreadPoolExecutor.

template<typename E >

Future<E>* decaf::util::concurrent::ExecutorService::submit	(	decaf::lang::Runnable *	task,
		bool	takeOwnership = true
	)			[inline]

Submits a Runnable object for execution.

A Future object is created and returned that will return the default value of the template type upon completion. The caller owns the returned pointer and is responsible for deleting it. The returned value is a proxy to the actual FutureTask that is submitted for execution so is legal for the caller to delete this value before its execution has completed.

Parameters:

	task	Pointer to a Runnable object that will be executed by this ExecutorService.
	takeOwnership	Boolean value indicating if the Executor now owns the pointer to the task.

Returns:

a new Future<?> pointer that is owned by the caller.

Exceptions:

	RejectedExecutionException	if the task cannot be scheduled for execution
	NullPointerException	if the Runnable pointer passed is NULL.

References DECAF_CATCH_RETHROW, DECAF_CATCHALL_THROW, decaf::lang::Pointer< T, REFCOUNTER >::get(), decaf::lang::Pointer< T, REFCOUNTER >::release(), and decaf::lang::Exception::setMark().

template<typename E >

Future<E>* decaf::util::concurrent::ExecutorService::submit	(	decaf::lang::Runnable *	task,
		const E &	result,
		bool	takeOwnership = true
	)			[inline]

Submits a Runnable task for execution and returns a Future representing that task.

The Future's get method will return the given result upon successful completion. The caller owns the returned pointer and is responsible for deleting it. The returned value is a proxy to the actual FutureTask that is submitted for execution so is legal for the caller to delete this value before its execution has completed.

Parameters:

	task	The pointer to the task to submit.
	result	The result to return
	takeOwnership	Boolean value indicating if the Executor now owns the pointer to the task.

Returns:

a Future<?> pointer representing pending completion of the task,

Exceptions:

	RejectedExecutionException	if the task cannot be scheduled for execution
	NullPointerException	if the task is null

References DECAF_CATCH_RETHROW, DECAF_CATCHALL_THROW, decaf::lang::Pointer< T, REFCOUNTER >::get(), decaf::lang::Pointer< T, REFCOUNTER >::release(), and decaf::lang::Exception::setMark().

template<typename E >

Future<E>* decaf::util::concurrent::ExecutorService::submit	(	Callable< E > *	task,
		bool	takeOwnership = true
	)			[inline]

Submits a value-returning task for execution and returns a Future pointer representing the pending results of the task.

The Future's get method will return the task's result upon successful completion. The caller owns the returned pointer and is responsible for deleting it. The returned value is a proxy to the actual FutureTask that is submitted for execution so is legal for the caller to delete this value before its execution has completed.

Parameters:

	task	Pointer to the Callable<?> task to submit.
	takeOwnership	Boolean value indicating if the Executor now owns the pointer to the task.

Returns:

a Future<?> pointer representing pending completion of the task.

Exceptions:

	RejectedExecutionException	if the task cannot be scheduled for execution
	NullPointerException	if the task is null

References DECAF_CATCH_RETHROW, DECAF_CATCHALL_THROW, decaf::lang::Pointer< T, REFCOUNTER >::get(), decaf::lang::Pointer< T, REFCOUNTER >::release(), and decaf::lang::Exception::setMark().

---

The documentation for this class was generated from the following file:

• src/main/decaf/util/concurrent/ExecutorService.h