class Token

Token that represents an acquired resource and can be used to release or re-acquire.

Tokens encapsulate the acquired resource and its limiter, allowing the resource to be released and re-acquired.

The token automatically tracks release state using the resource itself as the state indicator (nil = released, non-nil = acquired). A closed token also clears its limiter reference, which prevents future re-acquisition.

Definitions

def self.acquire(limiter, **options, &block)

  • asynchronous

Acquire a token from a limiter.

This class method provides a clean way to acquire tokens without adding token-specific methods to limiter classes.

Signature
parameter　limiter　Generic

The limiter to acquire from.

parameter　options　Hash

Acquisition options (timeout, cost, priority, etc.).

yields　{|token| ...}

Optional block executed with automatic token release.

parameter　token　Token

The acquired token object.

returns　Token, nil

A token object, or nil if acquisition failed.

raises　ArgumentError

If cost exceeds the timing strategy's maximum supported cost.

asynchronous

Implementation

 
def self.acquire(limiter, **options, &block)
	resource = limiter.acquire(**options)
	return nil unless resource
	
	token = new(limiter, resource)
	
	return token unless block_given?
	
	begin
		yield(token)
	ensure
		token.release
	end
end

def acquire(**options, &block)

  • asynchronous

Re-acquire the resource.

Signature
parameter　options　Hash

Acquisition options (timeout, cost, priority, etc.). Omitted options use the limiter's defaults.

yields　{|resource| ...}

Optional block executed with automatic token release.

parameter　resource　Object, nil

The acquired resource, or nil if acquisition failed.

returns　Object, nil

The acquired resource, or nil if acquisition failed or the token is closed. When used with a block, returns the result of the block execution unless the token is closed.

raises　RuntimeError

If the token is already acquired.

raises　ArgumentError

If the new cost exceeds timing strategy capacity.

asynchronous

Implementation

 
def acquire(**options, &block)
	raise "Token already acquired!" if @resource
	return nil unless @limiter
	
	@resource = @limiter.acquire(reacquire: true, **options)
	
	return @resource unless block_given?
	
	begin
		return yield(@resource)
	ensure
		self.release
	end
end

def initialize(limiter, resource = nil)

Initialize a new token.

Signature
parameter　limiter　Generic

The limiter that issued this token.

parameter　resource　Object

The acquired resource.

Implementation

 
def initialize(limiter, resource = nil)
	@limiter = limiter
	@resource = resource
end

attr_reader :resource

Signature
attribute　Object

The acquired resource (nil if released).

def release

Release the token back to the limiter.

Implementation

 
def release
	if resource = @resource
		@resource = nil
		@limiter.release(resource)
	end
end

def close

Close the token and prevent future re-acquisition.

Implementation

 
def close
	self.release
	@limiter = nil
end

def acquired?

Check if the token has been acquired.

Signature
returns　Boolean

True if the token has been acquired.

Implementation

 
def acquired?
	!!@resource
end

def released?

Check if the token has been released.

Signature
returns　Boolean

True if the token has been released.

Implementation

 
def released?
	!@resource
end

def closed?

Check if the token has been closed.

Signature
returns　Boolean

True if the token has been closed.

Implementation

 
def closed?
	!@limiter
end