com.atlassian.bitbucket.throttle

Interface ThrottleService

Deprecated.

since 7.9 without replacement for removal in 8.0

@Deprecated
public interface ThrottleService

Manages buckets of Tickets which may be used to throttle access to named resources. The exact semantics by which tickets are managed is not guaranteed by this interface, but it does have certain contracts:

• Attempting to acquire a ticket shall not block indefinitely, and acquire timeouts may be adjusted with settings in bitbucket.properties
• If acquiring a ticket for a named resource times out, a ResourceBusyException shall be thrown indicating the resource is busy
• If resources have been timing out, a banner shall be displayed in the user interface indicating the server is under heavy load
• When a server request ends, all tickets which were held during that request shall be released, whether they were explicitly released before the request ended or not

For tickets that are acquired on non-request threads, such as ExecutorService threads, it is the acquirer's obligation to ensure the ticket is released. The system will attempt to detect such "lost" tickets and release them, but such detection is "best effort" and may not be foolproof. In general, calling code should follow an approach similar to:

 Ticket ticket = throttleService.acquireTicket("resourceName");
 try {
     //Do protected, resource-intensive operation
 } finally {
     ticket.release();
 }
 

This ensures the ticket is released immediately after the resource-intensive operation being protected is completed, which, in turn, ensures the resource remains available and isn't starved out by "lost" tickets.

Method Summary

Modifier and Type	Method and Description
Ticket	acquireTicket(String resourceName) Deprecated. Acquires a ticket for accessing the specified resource.

Method Detail

acquireTicket

@Nonnull
Ticket acquireTicket(@Nonnull
                              String resourceName)
                       throws ResourceBusyException

Deprecated.

Acquires a ticket for accessing the specified resource.

Successful acquisition of a ticket indicates that the named resource should have sufficient capacity to service a single, full request. This means a ticket may be acquired once and held while multiple operations are performed on the gated resource. Callers should use finally blocks to ensure the ticket is released when they are finished using the gated resource. The system makes a best effort attempt to detect and release "lost" tickets when a server request ends, but it is best for callers to explicitly manage their own tickets as such detection may not catch all cases.

The returned Ticket will never be null. If no tickets are available for the requested resource, a ResourceBusyException will be thrown.

Parameters:

resourceName - the resource for which the ticket should be acquired

Returns:

the acquired ticket

Throws:

ResourceBusyException - if a ticket cannot be acquired from the named bucket