org.curjent.agent
Interface AgentTasks

All Known Implementing Classes:
DynamicTasks, FixedTasks, FTPTransferTasks, ReusableTask, SingletonTask

public interface AgentTasks

Source for agent tasks. See Description in org.curjent.agent for an overview of the role and implementation of agent tasks. In short, tasks implement their agent's interface methods, and calls to an agent are delegated to the agent's tasks for execution.

An implementation of AgentTasks determines the maximum number of threads an agent will use to concurrently execute calls. The agent will continue to acquire additional tasks until the acquire method returns null, or until the agent's queue of pending calls is exhausted. (The agent may occasionally and very briefly require additional threads for timing and efficiency reasons.)

In the simplest case, an AgentTasks implementation, such as SingletonTask, returns only one task. No explicit synchronization by the task is necessary in this case since only one call is executed at a time, and the agent ensures memory consistency across calls.

Some agents can improve throughput by using multiple threads. The ReusableTask implementation uses the same task for a specified maximum number of threads. In this case, the one task executes multiple calls concurrently, so it must be thread-safe. Alternative implementations include FixedTasks and DynamicTasks.

Agents assume calls to acquire and release are fast, in-memory operations. Furthermore, implementations of AgentTasks ideally avoid the extra overhead of thread-safety as this is provided by the agent.

Exceptions thrown by the acquire and release methods are propagated to the caller of the agent, if possible, or to the agent's handler for unhandled exceptions.

See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class), AgentConfig.setExecutor(Executor), AgentConfig.setUnhandledExceptionHandler(ExceptionHandler)

Method Summary
 Object acquire()
          Acquires a task.
 void release(Object task)
          Releases a task.
 

Method Detail

acquire

Object acquire()
               throws Throwable
Acquires a task. Returns null if no more tasks are available. The returned object's class must be equal to, or be a subclass of, the taskType used to create the agent.

Throws:
Throwable - An unexpected error.
See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)

release

void release(Object task)
             throws Throwable
Releases a task. The task argument is a non-null value previously returned from this instance's acquire method. Each call to acquire is paired with exactly one call to release for the same task.

Throws:
Throwable - An unexpected error.


Copyright 2009-2011 Tom Landon
Apache License 2.0