Terms

Following are the terms as used in this documentation and other WebSemaphore materials.

Consumer

Computer system calling remote API with potentially limitations on amount of calls per second or requests executed in parallel.

Provider

Computer system providing a rate-limited API. In case of rate limit excess, "429 - rate limit exceeded" error is returned.

Semaphore

In computer science, a semaphore is a variable or abstract data type used to control access to a common resource by multiple threads and avoid critical section problems in a concurrent system such as a multitasking operating system. Semaphores are a type of synchronization primitive. A trivial semaphore is a plain variable that is changed (for example, incremented or decremented, or toggled) depending on programmer-defined conditions. A useful way to think of a semaphore as used in a real-world system is as a record of how many units of a particular resource are available, coupled with operations to adjust that record safely (i.e., to avoid race conditions) as units are acquired or become free, and, if necessary, wait until a unit of the resource becomes available. - Wikipedia

WebSemaphore

WebSemaphore is a hybrid of a semaphore and queue acting in tandem to enable safe operations on critical and/or limited resources. It is scalable and fully serverless by design thereby avoiding many potential operational pitfalls of competing solutions, while staying lightweight and easily accessible.

The term's origin:

• By extension of the Semaphore concept, WebSemaphore is an always-on, highly available semaphore at the scale of the web. It just makes sense that one should be able to achieve such basic result without setting up servers and failover clusters, dealing with heavy and expensive PaaS solutions, or even worse - custom development. This is especially true when the user is looking to manage only a handful of streams.
• By extension of the Web Hook concept, WebSemaphore can be thought of as its younger but more resilient sibling.

ChannelId

The semaphores in WebSemaphore are multiplexable. A single semaphore can hold any number of separate streams that obey the rules of their owning semaphore. Each channel sticks to its own separate FIFO order.

[UPCOMING] Channel capacity may be limited to a total over a semaphore or individually by channel, thereby supporting a range of scenarios.

This feature is optional. When ChannelId is not used WebSemaphore will use the special channel name "default" for all communication.

If you are familiar with other messaging technologies, the channel functionality may be compared to a GroupId in SQS or a topic(?) in Kafka.

Limited resource

A resource that is enforcing a limit on the number of parallel connections or otherwise lacks the capacity to process the expected volume of requests.

Lock acquisition

In WebSemaphore, lock acquisition goes beyond counting the number of available resources, in particular when working in asynchronous mode. The acquisition is combined with a payload that is guaranteed to be delivered to the limited resource upon availability, and a subsequent release call. This flow differentiates WebSemaphore from more basic queueing mechanisms that would mostly consider their job done once the message is known to have been delivered.

Lock release

The lock release operation signals to WebSemaphore that the lock may be recycled. It is functioning identically in synchronous and asynchronous flows. This is a fire-and-forget operation from the client perspective.