org.curjent.agent
Annotation Type Capacity


@Documented
@Target(value=TYPE)
@Retention(value=RUNTIME)
public @interface Capacity

Specifies the maximum number of messages an agent accepts for processing. The agent throws a CapacityExceededException in response to subsequent calls.

The required accepted() element specifies how many messages the agent can immediately queue for processing, beyond which it throws a CapacityExceededException. Alternatively, instead of throwing an exception, the agent can suspend callers until it can accept more messages. The optional pending() element specifies how many pending callers the agent can suspend. Once the pending limit is reached, the agent throws a CapacityExceededException to subsequent callers. The optional timeout() element can also be used to specify the amount of time a caller waits for a pending message to be accepted before the call times out and the agent throws a CapacityExceededException.

Pending messages from multiple threads are added to the agent's queue in the order received. When an agent's message count drops below its message capacity, the first waiting call's message is added to the end of the agent's message queue. In other words, agents implement a fair fairness policy such that messages, including pending messages, are queued and processed in first-in, first-out (FIFO) order.

Note that the use of the pending element can lead to deadlock if two agents are suspended, each pending acceptance of the other's messages, either directly or indirectly.

Example usage scenarios:

    // At most 32 messages are accepted
    @Capacity(accepted=32)
    
    // Up to 64 callers can wait to be accepted
    @Capacity(accepted=32, pending=64)
    
    // Up to 64 callers can wait for one minute
    @Capacity(accepted=32, pending=64, timeout=60, unit=TimeUnit.SECONDS)
 

See Also:
AgentConfig, AgentConfig.setAcceptedCapacity(int), AgentConfig.setPendingCapacity(int), AgentConfig.setPendingTimeout(long, TimeUnit)

Required Element Summary
 int accepted
          Maximum number of messages an agent can immediately queue for processing.
 
Optional Element Summary
 int pending
          Maximum number of callers permitted to wait for the agent to accept new messages.
 long timeout
          Maximum duration a pending call waits.
 TimeUnit unit
          Time unit of the timeout().
 

Element Detail

accepted

public abstract int accepted
Maximum number of messages an agent can immediately queue for processing. Valid values range from 1 to Integer.MAX_VALUE.

pending

public abstract int pending
Maximum number of callers permitted to wait for the agent to accept new messages. Once pending number of callers are waiting, the agent responds immediately to subsequent calls with a CapacityExceededException. Valid values range from 0 to Integer.MAX_VALUE.

Default:
0

timeout

public abstract long timeout
Maximum duration a pending call waits. If the call times out, the agent throws a CapacityExceededException to the waiting caller. Valid values range from 1 to Long.MAX_VALUE. The time unit is specified by unit(). The default value is Long.MAX_VALUE.

Default:
9223372036854775807L

unit

public abstract TimeUnit unit
Time unit of the timeout(). May be null if the timeout value is Long.MAX_VALUE.

Default:
java.util.concurrent.TimeUnit.NANOSECONDS


Copyright 2009-2011 Tom Landon
Apache License 2.0