Dex.Limiter

Subclasses:

None

Methods

Inherited:

Dex.Object (2)

class	new (max_concurrency)
	acquire ()
	close ()
	close_after_drain ()
	get_max_concurrency ()
	release ()
	run (scheduler, stack_size, func, *func_data)
	run_coroutine (scheduler, func, *user_data)
	run_on_pool (pool, thread_func, *user_data)

Virtual Methods

None

Fields

None

Class Details

class Dex.Limiter

Bases:

Dex.Object

Abstract:

No

DexLimiter limits the number of operations running concurrently.

A limiter starts with a fixed number of permits. Use [method`Dex`.Limiter.acquire] and [method`Dex`.Limiter.release] directly when a permit must cover a custom scope, or use [method`Dex`.Limiter.run] or [method`Dex`.Limiter.run_on_pool] to acquire a permit and release it automatically when the work completes.

Added in version 1.2.

classmethod new(max_concurrency)

Parameters:

max_concurrency (int) – the maximum number of concurrent operations

Returns:

a new DexLimiter

Return type:

Dex.Limiter

Creates a new DexLimiter with max_concurrency permits.

max_concurrency must be greater than zero. Each successful acquisition consumes one permit until [method`Dex`.Limiter.release] is called.

Added in version 1.2.

acquire()

Returns:

a future that resolves when a permit is acquired

Return type:

Dex.Future

Acquires one permit from self.

The returned future resolves to True when a permit has been acquired. Call [method`Dex`.Limiter.release] exactly once for each resolved acquisition.

If the returned future is discarded before the permit is acquired, the permit is returned to the limiter when it becomes available. If self is closed before acquisition completes, the returned future rejects with Dex.Error.SEMAPHORE_CLOSED.

Added in version 1.2.

close()

Closes self.

Pending and future acquisitions reject with Dex.Error.SEMAPHORE_CLOSED. Permits already acquired remain valid, but releasing them after close will not make them available for new work.

Added in version 1.2.

close_after_drain()

Returns:

a [class`Dex`.Future] that resolves to true

Return type:

Dex.Future

Closes self and waits for all queued and running work to complete.

After this function is called, new acquire attempts are rejected with Dex.Error.SEMAPHORE_CLOSED.

The returned future resolves to %TRUE once all outstanding pending acquire futures and held permits are complete. Existing permit holders must still eventually release.

Added in version 1.2.

get_max_concurrency()

Returns:

the maximum number of concurrent operations

Return type:

int

Gets the maximum number of permits available from self.

Added in version 1.2.

release()

Releases one permit previously acquired from self.

This must be called exactly once for each successful [method`Dex`.Limiter.acquire] unless the permit is managed by [method`Dex`.Limiter.run].

Added in version 1.2.

run(scheduler, stack_size, func, *func_data)

Parameters:

• scheduler (Dex.Scheduler or None) – scheduler to spawn func on, or None for the thread default

• stack_size (int) – stack size for the spawned fiber, or zero to use the default

• func (Dex.FiberFunc) – fiber function to run after a permit is acquired

• func_data (object or None) – closure data for func

Returns:

a future representing the spawned fiber

Return type:

Dex.Future

Runs func while holding one permit from self.

The returned future resolves or rejects with the result of the spawned fiber. The permit is released automatically after the fiber resolves or rejects. If the returned future is discarded after the fiber starts, the fiber is allowed to complete so that the permit can be released.

Added in version 1.2.

run_coroutine(scheduler, func, *user_data)

Parameters:

• scheduler (Dex.Scheduler or None) – scheduler to spawn func on, or None for the thread default

• func (Dex.CoroutineFunc) – coroutine function to run after a permit is acquired

• user_data (object or None) – closure data for func

Returns:

a future representing the spawned coroutine

Return type:

Dex.Future

Runs func while holding one permit from self.

The returned future resolves or rejects with the result of the spawned coroutine. The permit is released automatically after the coroutine resolves or rejects. If the returned future is discarded after the coroutine starts, the coroutine is allowed to complete so that the permit can be released.

Added in version 1.2.

run_on_pool(pool, thread_func, *user_data)

Parameters:

• pool (Dex.ThreadPool) – a DexThreadPool

• thread_func (Dex.ThreadFunc) – function to run on pool after a permit is acquired

• user_data (object or None) – closure data for thread_func

Returns:

a future representing the submitted work

Return type:

Dex.Future

Runs thread_func on pool while holding one permit from self.

The returned future resolves or rejects with the result of the submitted thread-pool work. The permit is released automatically after the work resolves or rejects. If the returned future is discarded after the work is submitted to pool, the work is allowed to complete so that the permit can be released.

Workers in DexThreadPool are not scheduler threads, so thread_func must not use dex_await().

Added in version 1.2.