ThrottleService

Class Overview

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.

Summary

Public Methods
@Nonnull Ticket	acquireTicket(String resourceName) Acquires a ticket for accessing the specified resource.