com.sleepycat.je.utilint

Class TaskCoordinator

java.lang.Object

com.sleepycat.je.utilint.TaskCoordinator

Direct Known Subclasses:

JETaskCoordinator

public class TaskCoordinator
extends Object

The base class that coordinates tasks via the distribution of permits to cooperating tasks or the application itself. Housekeeping tasks acquire and release permits as needed using the acquirePermit(Task, long, long, TimeUnit) and releasePermit(Permit) pair of methods. The application controls the supply of permits available to the housekeeping tasks via setAppPermitPercent(int), increasing the percentage of permits it retains as it gets busy and decreasing the percentage when the load diminishes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	TaskCoordinator.Permit Permits acquired by Tasks are represented by Permit objects.
static interface	TaskCoordinator.StatDefs Defines stats associated with the TaskCoordinator.
static class	TaskCoordinator.Task Represents a task that can request permits.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_LEASE_CHECK_PERIOD_MS The default period used to run the lease checking task.
protected Logger	logger
protected Timer	timer

Constructor Summary

Constructors

Constructor and Description
TaskCoordinator(Logger logger, Set<TaskCoordinator.Task> tasks) The constructor used to create active coordinators.
TaskCoordinator(Logger logger, Set<TaskCoordinator.Task> tasks, boolean active) The constructor used to initialize the set of cooperating tasks.

Method Summary

Modifier and Type	Method and Description
TaskCoordinator.Permit	acquirePermit(TaskCoordinator.Task task, long timeout, long leaseInterval, TimeUnit unit) Returns a Permit.
void	close() Close the coordinator.
int	getAppPermitPercent() Returns the % of total permits current reserved by the application.
int	getAppPermits() Returns the current number of app permits reserved by the application.
int	getAvailableRealPermits() The number of real permits available for acquisition by housekeeping tasks.
int	getMaxPermits() Returns the constant maximum number of real permits available to housekeeping tasks.
int	getOutstandingDeficitPermits() Returns the number of currently outstanding deficit permits
int	getOutstandingRealPermits() Returns the number of currently outstanding real permits.
StatGroup	getStats(StatsConfig statsConfig) Returns the stats associated with the Task Coordinator.
protected String	permitSummary() Log information about current use of permits
void	releasePermit(TaskCoordinator.Permit permit) Releases the permit that was acquired by an earlier call to acquirePermit(com.sleepycat.je.utilint.TaskCoordinator.Task, long, long, java.util.concurrent.TimeUnit).
boolean	setAppPermitPercent(int newAppPermitPercent) Used to adjust the number of permits associated with the application.
void	setLeaseCheckingPeriod(int periodMs) Modifies the lease period.

Methods inherited from class java.lang.Object

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

Field Detail

timer

protected final Timer timer

DEFAULT_LEASE_CHECK_PERIOD_MS

public static final int DEFAULT_LEASE_CHECK_PERIOD_MS

The default period used to run the lease checking task.

See Also:

Constant Field Values

logger

protected final Logger logger

Constructor Detail

TaskCoordinator

public TaskCoordinator(Logger logger,
                       Set<TaskCoordinator.Task> tasks,
                       boolean active)

The constructor used to initialize the set of cooperating tasks. A coordinator can be rendered inactive, by passing "false" to the active argument. An inactive coordinator will always give out a real permit (never a deficit permit), without waiting, when one is requested via acquirePermit(com.sleepycat.je.utilint.TaskCoordinator.Task, long, long, java.util.concurrent.TimeUnit), thus effectively disabling the coordination mechanism. Note that leases, if specified, are still tracked against these permits. This is to ensure that the behavior of the code is correct and no permits are being leaked.

Parameters:

logger - the logger used for task coordination related logging

tasks - the set of cooperating tasks

active - if true the coordinator is active

TaskCoordinator

public TaskCoordinator(Logger logger,
                       Set<TaskCoordinator.Task> tasks)

The constructor used to create active coordinators.

See Also:

TaskCoordinator(Logger, Set, boolean)

Method Detail

setLeaseCheckingPeriod

public void setLeaseCheckingPeriod(int periodMs)

Modifies the lease period. Used primarily for testing.

Parameters:

periodMs - the new period; turns off lease checking if the period is zero

getMaxPermits

public int getMaxPermits()

Returns the constant maximum number of real permits available to housekeeping tasks. Note: This function will return Integer.MAX_VALUE when the coordinator was initialized to be inactive.

getAppPermits

public int getAppPermits()

Returns the current number of app permits reserved by the application. These permits are not available for acquisition by housekeeping tasks.

getAppPermitPercent

public int getAppPermitPercent()

Returns the % of total permits current reserved by the application.

getAvailableRealPermits

public int getAvailableRealPermits()

The number of real permits available for acquisition by housekeeping tasks. Note that this number can be negative, due to the existence of outstanding deficit permits, or due to an async increase in permits reserved by the application.

getOutstandingDeficitPermits

public int getOutstandingDeficitPermits()

Returns the number of currently outstanding deficit permits

getOutstandingRealPermits

public int getOutstandingRealPermits()

Returns the number of currently outstanding real permits. These are permits that have been acquired but not yet released.

acquirePermit

public TaskCoordinator.Permit acquirePermit(TaskCoordinator.Task task,
                                            long timeout,
                                            long leaseInterval,
                                            TimeUnit unit)
                                     throws InterruptedException

Returns a Permit. The timeout determines how long the application is prepared to wait cooperatively for a permit.

If a permit cannot be granted within the timeout period, a deficit permit (TaskCoordinator.Permit.isDeficit() is granted. The requester can choose to release the permit immediately or proceed with its task in any case and release the permit later. Returning a deficit permit reduces the supply of permits by one; the supply is restored when the deficit permit is released.

A permit can optionally be associated with an extensible (via Permit#setLease) lease period. This mechanism is primarily intended to be a debugging aid to detect Permits which were acquired but not released. The permit is effectively released after it has expired by a background thread thus freeing up its resources. Such "potentially" leaked permits are logged as an aid to debugging. Attempts to access them after the lease has expired will result in an IllegalStateException.

Parameters:

task - the task acquiring the permit. It must be one of the cooperating tasks, supplied when the coordinator was created.

timeout - the amount of time to wait for the permits. If the value is zero don't wait.

leaseInterval - the max amount of time that a permit can be retained after it is acquired before it must be released.

unit - the time unit of the timeout and @code leaseInterval arguments

Returns:

Permit the returned Permit. It could be a deficit permit if one could not be obtained in the timeout interval.

Throws:

InterruptedException - if the thread is interrupted. The request to acquire the permit is abandoned in this case. The state of the coordinator is not impacted by the interrupt and the application can proceed to acquire other permits or close() the coordinator.

See Also:

releasePermit(Permit), TaskCoordinator.Permit.setLease(long, java.util.concurrent.TimeUnit)

releasePermit

public void releasePermit(TaskCoordinator.Permit permit)

Releases the permit that was acquired by an earlier call to acquirePermit(com.sleepycat.je.utilint.TaskCoordinator.Task, long, long, java.util.concurrent.TimeUnit). It's up to the application to ensure correct pairing of an acquirePermit(com.sleepycat.je.utilint.TaskCoordinator.Task, long, long, java.util.concurrent.TimeUnit) and releasePermit(com.sleepycat.je.utilint.TaskCoordinator.Permit) pair. An IllegalStateException is thrown if the lease associated with the permit has expired or an attempt is made to release a permit that was already released.

Parameters:

permit - the permit being released

See Also:

acquirePermit(Task, long, long, TimeUnit)

setAppPermitPercent

public boolean setAppPermitPercent(int newAppPermitPercent)

Used to adjust the number of permits associated with the application. It does this by varying the number of permits available to the tasks. Any permits associated with it are not available for acquisition by tasks. The application invokes this method whenever it detects a change in its load characteristics. If it detects an increase in its load, it should increase the percentage of permits it reserves for itself and vice versa.

Parameters:

newAppPermitPercent - the percentage of permits to be reserved for the application. The higher this percentage, the fewer the permits available for use by the housekeeping tasks. It must be a number between 0 and 100

Returns:

true if the number of application permits were changed

close

public void close()

Close the coordinator. All currently waiting tasks are released by issuing a deficit permit. All subsequent calls to acquirePermit(com.sleepycat.je.utilint.TaskCoordinator.Task, long, long, java.util.concurrent.TimeUnit) will result in the return of a DeficitPermit. It's up to the individual tasks to check for application shutdown and do their own individual cleanup.

getStats

public StatGroup getStats(StatsConfig statsConfig)

Returns the stats associated with the Task Coordinator. Note that statsConfig is unused since all the TaskCoordinator stats are just instantaneous stats.

permitSummary

protected String permitSummary()

Log information about current use of permits