Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Semaphore

Limits access to a pool of resources by restricting how many callers can run at a time. Any callers above the allowed amount will be queued until a spot is released.

Best Practices

  • Whether your operation succeeds or fails, always call release() to ensure the next caller can proceed. Calling release() inside a finally block makes this easy. See the example below.
example
import { fetch, createRequest } from '~/path/to/datalayer';
import { tracker } from '~/path/to/tracker';

const uploadSpots = signals.semaphore(5);
const operation = {
  base: 'files',
  method: 'POST',
  path: '/save/:id'
};

export async function uploadFile(blob) {
  const data = new FormData();
  const params = { id: tracker.uuid() };
  data.append('file', blob, params.id);
  try {
    await uploadSpots.ready();
    await fetch(createRequest(operation, params, data));
    return params.id;
  } finally {
    uploadSpots.release(); // always release
  }
}

Hierarchy

Index

Properties

Methods

Properties

available

available: number

The number of spots currently available for callers before they will be queued.

readonly
example
const spots = signals.semaphore(10);

spots.ready().then(doSomething).finally(spots.release);

console.log(spots.queued); // 0
console.log(spots.running); // 1
console.log(spots.available); // 9

queued

queued: number

The number of callers that are still waiting to run.

readonly
example
const spots = signals.semaphore(2);

spots.ready().then(doSomething).finally(spots.release);
spots.ready().then(doSomethingElse).finally(spots.release);
spots.ready().then(doAnotherThing).finally(spots.release);

console.log(spots.queued); // 1
console.log(spots.running); // 2
console.log(spots.available); // 0

running

running: number

The number of callers currently running. Callers must always remember to call release() when done to ensure this number is decremented appropriately.

readonly
example
const spots = signals.semaphore(10);

spots.ready().then(doSomething).finally(spots.release);

console.log(spots.queued); // 0
console.log(spots.running); // 1
console.log(spots.available); // 9

Methods

ready

  • ready(): Promise<void>

  • Queues the caller until a spot is available.

    example
    const spots = signals.semaphore(2);

    export async function doSomething() {
      await spots.ready();
      try {
        // do stuff
      } finally {
        spots.release();
      }
    }

    Returns Promise<void>

    A Promise that will be resolved when a slot is available.

release

  • release(count?: number): void

  • Notifies the semaphore that the given number of slots have become available. If any callers have been queued, they will be run in the newly available slots.

    example
    const spots = signals.semaphore(2);

    spots.ready()
      .then(doSomething)
      .finally(spots.release);
    example
    const spots = signals.semaphore();

    Promise.all([
      spots.ready().then(firstOperation),
      spots.ready().then(secondOperation)
    ]).finally(() => spots.release(2));
    example
    const spots = signals.semaphore(10);

    export async function doSomething() {
      await spots.ready();
      try {
        // code
      } finally {
        spots.release();
      }
    }

    Parameters

    • Optional count: number

      The number to spots to make available.

    Returns void