@NotThreadSafe public interface Ticket extends AutoCloseable
named resource. When the resource is no longer needed, the ticket
holder should close their ticket, allowing another request to acquire it. The preferred approach
for this is to use a try-with-resources block:
try (Ticket ticket = throttleService.acquireTicket("scm-command")) {
//Do work, knowing the ticket will always be closed
}Note: The maximum duration for a ticket is scoped to the surrounding operation (where "operation" may be an HTTP request, an executed task or some other arbitrary unit of work). The system forcibly releases any tickets which are still held at the end of that bounding operation, where possible. This is done to help prevent resource starvation due to "lost" tickets, which are never otherwise released by their holding code.
Warning: Tickets are not thread-safe, and should never be passed across threads. Acquiring a ticket on one thread and releasing it on another thread will fail.
If a thread submits a Runnable on the ExecutorService exposed by the system or on any of the
delegating ExecutorServices created by SAL's ThreadLocalDelegateExecutorFactory while holding a ticket,
then the executor thread will implicitly inherit an internal "stub" of the calling thread's ticket. This "stub"
ticket will act like a real ticket for the purposes of subsequent calls to the ThrottleService
(preventing multiple tickets from being acquired in nested calls to ThrottleService.acquireTicket(String)
for example), but will not actually count towards the named resource and will not affect the calling thread's ticket
in any way when released. A thread created in any other way (for example, with
ThreadFactory or by submitting a Runnable to a
Executor) does not inherit any ticket state from the calling thread, and must
acquire its own ticket independently by calling ThrottleService.acquireTicket(String)) if it wants to
throttle access to the same resource. Any such tickets acquired in this way must be released with
close() after the resource-intensive work has been done, to ensure no tickets are ever "lost".
ThrottleService| Modifier and Type | Method and Description |
|---|---|
void |
close()
Releases the ticket, indicating the named resource is now available to service another request.
|
String |
getResourceName()
Retrieves the name of the resource to which this ticket grants access.
|
void close()
The system performs best effort detection of "lost" tickets and attempts to release them. However, it is better for ticketholders to release their own tickets after the guarded operation has been performed. This both reduces the duration during which the ticket is locked, allowing other code to acquire the ticket more readily, and helps ensure all tickets are eventually released.
close in interface AutoCloseableCopyright © 2019 Atlassian. All rights reserved.