effect-distributed-lock 0.0.4 → 0.0.6

package/README.md

@@ -12,6 +12,7 @@ It's like the built in `Effect.Semaphore`, but asynchronously distributed across
 - **Scope-based resource management** — permits are automatically released when the scope closes
 - **Automatic TTL refresh** — keeps permits alive while held, prevents deadlocks if holder crashes
 - **Pluggable backends** — ships with Redis (single-instance), easy to implement others
+- **Push-based waiting** — uses pub/sub for efficient notification when permits become available (optional, with polling fallback)
 - **Configurable retry policies** — control polling interval, TTL, and backing failure retry behavior
 - **Type-safe errors** — tagged errors for precise error handling
 
@@ -34,7 +35,7 @@ import Redis from "ioredis";
 import { DistributedSemaphore, RedisBacking } from "effect-distributed-lock";
 
 const redis = new Redis(process.env.REDIS_URL);
-const RedisLayer = RedisBacking.layer(redis);
+const RedisLayer = RedisBacking.layer(redis, { keyPrefix: "my-app:" });
 
 const program = Effect.gen(function* () {
   // Create a semaphore that allows 5 concurrent operations
@@ -112,6 +113,72 @@ yield* Effect.scoped(
 
 Both `take` and `tryTake` return the keepalive fiber that refreshes the permit TTL. Errors from the keepalive (losing permits or backing store failure) are propagated through the fiber.
 
+### Acquire Options
+
+All acquire methods (`withPermits`, `withPermitsIfAvailable`, `take`, `tryTake`) accept an optional second parameter for advanced use cases:
+
+```typescript
+yield* myEffect.pipe(sem.withPermits(1, { identifier: "my-custom-id" }));
+```
+
+| Option              | Type      | Default              | Description                                      |
+| ------------------- | --------- | -------------------- | ------------------------------------------------ |
+| `identifier`        | `string`  | `crypto.randomUUID()` | Unique ID for this permit holder                 |
+| `acquiredExternally`| `boolean` | `false`              | Assume permits already held, use refresh to verify |
+
+#### Custom Identifiers
+
+By default, a random UUID is generated for each acquire. Override this for:
+- **Debugging/observability**: Use meaningful identifiers to trace lock holders
+- **Cross-process handoff**: Share identifiers between processes
+
+```typescript
+// Custom identifier for debugging
+yield* myEffect.pipe(sem.withPermits(1, { identifier: "worker-1-job-123" }));
+```
+
+⚠️ **Warning**: Identifiers must be unique across concurrent holders. Using the same identifier from different processes will cause them to be treated as the same holder.
+
+#### Resuming After Crash (`acquiredExternally`)
+
+Use `acquiredExternally: true` to resume ownership of permits that were acquired previously but not properly released (e.g., after a process crash). This uses `refresh` instead of `acquire` to verify ownership.
+
+```typescript
+// Store identifier persistently before doing work
+const identifier = crypto.randomUUID();
+yield* saveToDatabase({ jobId, lockIdentifier: identifier });
+
+yield* Effect.gen(function* () {
+  yield* doWork();
+  yield* deleteFromDatabase(jobId);
+}).pipe(sem.withPermits(1, { identifier }));
+
+// === Later, after crash recovery ===
+const { lockIdentifier } = yield* loadFromDatabase(jobId);
+
+// Check if we still hold the lock (TTL hasn't expired)
+const result = yield* Effect.gen(function* () {
+  yield* resumeWork();
+  yield* deleteFromDatabase(jobId);
+}).pipe(
+  sem.withPermitsIfAvailable(1, { 
+    identifier: lockIdentifier, 
+    acquiredExternally: true 
+  })
+);
+
+if (Option.isNone(result)) {
+  // Lock expired, need to re-acquire normally
+  yield* restartWork().pipe(sem.withPermits(1));
+}
+```
+
+This is useful for:
+- **Crash recovery**: Resume work if you crashed while holding permits
+- **Process restart**: Check if your previous lock is still valid
+
+⚠️ **Unsafe**: If the identifier is wrong or the lock expired, `tryTake`/`withPermitsIfAvailable` return `None`, while `take`/`withPermits` keep retrying forever (waiting for permits that will never come).
+
 #### `currentCount` — Check held permits
 
 ```typescript
@@ -150,7 +217,37 @@ import { RedisBacking } from "effect-distributed-lock";
 
 // Single Redis instance
 const redis = new Redis("redis://localhost:6379");
-const RedisLayer = RedisBacking.layer(redis, "my-prefix:");
+const RedisLayer = RedisBacking.layer(redis, {
+  keyPrefix: "my-prefix:",
+  pushBasedAcquireEnabled: true, // default: true
+});
+```
+
+### Configuration Options
+
+| Option                     | Type             | Default            | Description                                          |
+| -------------------------- | ---------------- | ------------------ | ---------------------------------------------------- |
+| `keyPrefix`                | `string`         | `"semaphore:"`     | Prefix for all Redis keys                            |
+| `pushBasedAcquireEnabled`  | `boolean`        | `true`             | Use pub/sub for efficient waiting (see below)        |
+| `pushStreamRetrySchedule`  | `Schedule<void>` | `Schedule.forever` | Retry schedule for pub/sub stream errors             |
+
+### Push-Based Acquisition
+
+By default, the Redis backing uses pub/sub to notify waiters when permits become available. This reduces latency and load on Redis compared to pure polling.
+
+When permits are released, a message is published to a channel. Waiters subscribe to this channel and immediately attempt to acquire when notified. The semaphore still falls back to polling as a safety net.
+
+**Trade-offs:**
+- ✅ Lower latency — waiters are notified immediately
+- ✅ Reduced Redis load — fewer polling requests
+- ⚠️ Extra connection — each waiting semaphore uses a subscriber connection
+
+To disable and use polling only:
+
+```typescript
+const RedisLayer = RedisBacking.layer(redis, {
+  pushBasedAcquireEnabled: false,
+});
 ```
 
 For multi-instance Redis deployments requiring Redlock, you'll need to implement a custom backing.
@@ -160,7 +257,7 @@ For multi-instance Redis deployments requiring Redlock, you'll need to implement
 Implement the `DistributedSemaphoreBacking` interface to use a different store:
 
 ```typescript
-import { Duration, Effect, Layer, Option } from "effect";
+import { Duration, Effect, Layer, Stream } from "effect";
 import { Backing, DistributedSemaphoreBacking } from "effect-distributed-lock";
 
 const MyCustomBacking = Layer.succeed(DistributedSemaphoreBacking, {
@@ -175,16 +272,23 @@ const MyCustomBacking = Layer.succeed(DistributedSemaphoreBacking, {
   
   getCount: (key, ttl) => 
     Effect.succeed(0), // Return number of permits currently held
+
+  // Optional: Enable push-based waiting
+  onPermitsReleased: (key) => 
+    Stream.never, // Stream that emits when permits MAY be available
 });
 ```
 
+The `onPermitsReleased` method is optional. If provided, the semaphore will use it for efficient push-based waiting instead of pure polling. The stream should emit whenever permits are released on the given key. Multiple waiters may race for permits after a notification, so `tryAcquire` is still called after each notification.
+
 ## How It Works
 
 1. **Acquire**: Atomically adds permits to a sorted set if there's room (Redis: Lua script with `ZADD`)
 2. **Keepalive**: A background fiber refreshes the TTL periodically by updating timestamps
-3. **Release**: Atomically removes permits from the sorted set (Lua script with `ZREM`)
-4. **Expiration**: Expired entries (based on TTL) are cleaned up on each operation
-5. **Crash safety**: If the holder crashes, permits expire and become available
+3. **Release**: Atomically removes permits and publishes notification to waiters (Lua script with `ZREM` + `PUBLISH`)
+4. **Waiting**: Combines polling with pub/sub notifications — waiters are notified immediately when permits are released
+5. **Expiration**: Expired entries (based on TTL) are cleaned up on each operation
+6. **Crash safety**: If the holder crashes, permits expire and become available
 
 ## License
 

package/examples/index.ts

@@ -12,7 +12,9 @@ import { DistributedSemaphore, RedisBacking } from "../src/index.ts";
 const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
 
 // Create the Redis backing layer
-const RedisLayer = RedisBacking.layer(redis, "example:");
+const RedisLayer = RedisBacking.layer(redis, {
+  keyPrefix: "example:",
+});
 
 // Example 1: Using withPermits for a critical section (mutex behavior)
 const example1 = Effect.gen(function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-distributed-lock",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "A distributed semaphore library for Effect with pluggable backends",
   "license": "MIT",
   "repository": {

package/src/Backing.ts

@@ -1,4 +1,4 @@
-import { Context, Data, Duration, Effect } from "effect";
+import { Context, Data, Duration, Effect, Stream } from "effect";
 
 // =============================================================================
 // Errors
@@ -24,22 +24,12 @@ export class SemaphoreBackingError extends Data.TaggedError(
 
 /**
  * Low-level backing store interface for distributed semaphore operations.
- * Implementations handle the actual storage (Redis, etc.)
- *
- * The semaphore uses a sorted set model where:
- * - Each permit holder is stored with their acquisition timestamp as the score
- * - Expired entries are cleaned up automatically
- * - Multiple permits can be acquired atomically
  */
 export interface DistributedSemaphoreBacking {
   /**
    * Try to acquire `permits` from a semaphore with the given `limit`.
-   * Returns true if acquired, false if not enough permits available.
    *
-   * The implementation should:
-   * 1. Clean up expired entries (based on TTL)
-   * 2. Check if there's room: currentCount + permits <= limit
-   * 3. If so, add the permits with current timestamp
+   * @returns `true` if acquired, `false` if not enough permits available.
    */
   readonly tryAcquire: (
     key: string,
@@ -50,8 +40,9 @@ export interface DistributedSemaphoreBacking {
   ) => Effect.Effect<boolean, SemaphoreBackingError>;
 
   /**
-   * Release `permits` held by this holder.
-   * Returns the number of permits actually released.
+   * Release `permits` held by the given holder.
+   *
+   * @returns The number of permits actually released.
    */
   readonly release: (
     key: string,
@@ -60,8 +51,9 @@ export interface DistributedSemaphoreBacking {
   ) => Effect.Effect<number, SemaphoreBackingError>;
 
   /**
-   * Refresh the TTL on permits we hold.
-   * Returns true if refreshed, false if permits were lost.
+   * Refresh the TTL on permits held by this holder.
+   *
+   * @returns `true` if refreshed, `false` if permits were lost (e.g., expired).
    */
   readonly refresh: (
     key: string,
@@ -73,12 +65,24 @@ export interface DistributedSemaphoreBacking {
 
   /**
    * Get the number of permits currently held (in use).
-   * Available permits = limit - getCount().
    */
   readonly getCount: (
     key: string,
     ttl: Duration.Duration
   ) => Effect.Effect<number, SemaphoreBackingError>;
+
+  /**
+   * Optional: Stream of notifications when permits MAY be available.
+   *
+   * If provided, the semaphore layer uses this for efficient waiting instead
+   * of polling. The stream emits a signal whenever permits are released.
+   *
+   * Notes:
+   * - Multiple waiters may race for permits after a notification
+   * - The semaphore still calls `tryAcquire` after each notification
+   * - Implementations should handle reconnection internally (hence why the stream does not have an error type)
+   */
+  readonly onPermitsReleased?: (key: string) => Stream.Stream<void>;
 }
 
 export const DistributedSemaphoreBacking =

package/src/DistributedSemaphore.ts

@@ -3,9 +3,11 @@ import {
   Duration,
   Effect,
   Fiber,
+  Function,
   Option,
   Schedule,
   Scope,
+  Stream,
 } from "effect";
 import {
   DistributedSemaphoreBacking,
@@ -40,9 +42,9 @@ export interface DistributedSemaphoreConfig {
 
   /**
    * How often to poll when waiting to acquire permits.
-   * @default 100ms
+   * @default Schedule.spaced(Duration.millis(100))
    */
-  readonly acquireRetryInterval?: Duration.DurationInput;
+  readonly acquireRetryPolicy?: Schedule.Schedule<void>;
 
   /**
    * Retry policy when a backing failure occurs.
@@ -50,16 +52,58 @@ export interface DistributedSemaphoreConfig {
    * - Trying to acquire permits
    * - Refreshing the TTL
    * - Releasing permits
+   * @default Schedule.recurs(3)
    */
   readonly backingFailureRetryPolicy?: Schedule.Schedule<void>;
 }
 
 const DEFAULT_LIMIT = 1;
 const DEFAULT_TTL = Duration.seconds(30);
-const DEFAULT_ACQUIRE_RETRY_INTERVAL = Duration.millis(100);
-const DEFAULT_FAILURE_RETRY_POLICY = Schedule.spaced(
-  DEFAULT_ACQUIRE_RETRY_INTERVAL
-).pipe(Schedule.asVoid);
+const DEFAULT_ACQUIRE_RETRY_POLICY = Schedule.spaced(Duration.millis(100)).pipe(
+  Schedule.asVoid
+);
+const DEFAULT_FAILURE_RETRY_POLICY = Schedule.recurs(3).pipe(Schedule.asVoid);
+
+// =============================================================================
+// Acquire Options
+// =============================================================================
+
+/**
+ * Options for acquire operations (take, tryTake, withPermits, etc.)
+ */
+export interface AcquireOptions {
+  /**
+   * Unique identifier for this permit holder.
+   *
+   * By default, a random UUID is generated per-acquire. Override this if you need:
+   * - Predictable identifiers for debugging/observability
+   * - Cross-process lock handoff (acquire in one process, release in another)
+   *
+   * ⚠️ **Warning**: Must be unique across concurrent holders, otherwise locks with the same
+   * identifier may be treated as the same holder.
+   *
+   * @default crypto.randomUUID()
+   */
+  readonly identifier?: string;
+
+  /**
+   * If true, assumes the permits were already acquired externally with the given identifier.
+   * Instead of acquiring, uses refresh to verify ownership.
+   *
+   * **Requires `identifier` to be provided.**
+   *
+   * This is useful for cross-process lock handoff:
+   * 1. Process A acquires permits with a known identifier
+   * 2. Process A passes the identifier to Process B (via message queue, etc.)
+   * 3. Process B calls take/withPermits with `{ identifier, acquiredExternally: true }`
+   * 4. Process B now owns the permits (refreshing and releasing)
+   *
+   * ⚠️ **Unsafe**: If the identifier is wrong or the lock expired, this will fail immediately.
+   *
+   * @default false
+   */
+  readonly acquiredExternally?: boolean;
+}
 
 // =============================================================================
 // Distributed Semaphore Interface
@@ -107,7 +151,8 @@ export interface DistributedSemaphore {
    * The permit TTL is refreshed automatically while the effect runs.
    */
   readonly withPermits: (
-    permits: number
+    permits: number,
+    options?: AcquireOptions
   ) => <A, E, R>(
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E | LockLostError | SemaphoreBackingError, R>;
@@ -118,7 +163,8 @@ export interface DistributedSemaphore {
    * None if permits were not available.
    */
   readonly withPermitsIfAvailable: (
-    permits: number
+    permits: number,
+    options?: AcquireOptions
   ) => <A, E, R>(
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<
@@ -136,7 +182,8 @@ export interface DistributedSemaphore {
    * When the scope closes, the fiber is interrupted and permits are released.
    */
   readonly take: (
-    permits: number
+    permits: number,
+    options?: AcquireOptions
   ) => Effect.Effect<
     Fiber.Fiber<never, LockLostError | SemaphoreBackingError>,
     LockLostError | SemaphoreBackingError,
@@ -152,7 +199,8 @@ export interface DistributedSemaphore {
    * When the scope closes, the fiber is interrupted and permits are released.
    */
   readonly tryTake: (
-    permits: number
+    permits: number,
+    options?: AcquireOptions
   ) => Effect.Effect<
     Option.Option<Fiber.Fiber<never, LockLostError | SemaphoreBackingError>>,
     LockLostError | SemaphoreBackingError,
@@ -174,7 +222,7 @@ type FullyResolvedConfig = {
   limit: number;
   ttl: Duration.Duration;
   refreshInterval: Duration.Duration;
-  acquireRetryInterval: Duration.Duration;
+  acquireRetryPolicy: Schedule.Schedule<void>;
   backingFailureRetryPolicy: Schedule.Schedule<void>;
 };
 
@@ -186,9 +234,9 @@ function fullyResolveConfig(
   const refreshInterval = config.refreshInterval
     ? Duration.decode(config.refreshInterval)
     : Duration.millis(Duration.toMillis(ttl) / 3);
-  const acquireRetryInterval = config.acquireRetryInterval
-    ? Duration.decode(config.acquireRetryInterval)
-    : DEFAULT_ACQUIRE_RETRY_INTERVAL;
+  const acquireRetryPolicy = config.acquireRetryPolicy
+    ? config.acquireRetryPolicy
+    : DEFAULT_ACQUIRE_RETRY_POLICY;
   const backingFailureRetryPolicy = config.backingFailureRetryPolicy
     ? config.backingFailureRetryPolicy
     : DEFAULT_FAILURE_RETRY_POLICY;
@@ -197,7 +245,7 @@ function fullyResolveConfig(
     limit,
     ttl,
     refreshInterval,
-    acquireRetryInterval,
+    acquireRetryPolicy,
     backingFailureRetryPolicy,
   };
 }
@@ -228,15 +276,12 @@ export const make = (
   Effect.gen(function* () {
     const backing = yield* DistributedSemaphoreBacking;
 
-    // Generate unique holder ID for this instance
-    const holderId = crypto.randomUUID();
-
     // Resolve config with defaults
     const {
       limit,
       ttl,
       refreshInterval,
-      acquireRetryInterval,
+      acquireRetryPolicy,
       backingFailureRetryPolicy,
     } = fullyResolveConfig(config);
 
@@ -253,12 +298,13 @@ export const make = (
     // Keep the permits alive by refreshing TTL periodically.
     // This effect runs forever until interrupted (when scope closes).
     const keepAlive = (
+      identifier: string,
       permits: number
     ): Effect.Effect<never, SemaphoreBackingError | LockLostError, never> =>
       Effect.repeat(
         Effect.gen(function* () {
           const refreshed = yield* backing
-            .refresh(key, holderId, ttl, limit, permits)
+            .refresh(key, identifier, ttl, limit, permits)
             .pipe(withBackingErrorRetry);
 
           if (!refreshed) {
@@ -276,27 +322,40 @@ export const make = (
 
     // Try to acquire permits immediately, returns Option
     const tryTake = (
-      permits: number
+      permits: number,
+      options?: AcquireOptions
     ): Effect.Effect<
       Option.Option<Fiber.Fiber<never, LockLostError | SemaphoreBackingError>>,
       SemaphoreBackingError,
       Scope.Scope
     > =>
       Effect.gen(function* () {
-        const acquired = yield* backing
-          .tryAcquire(key, holderId, ttl, limit, permits)
-          .pipe(withBackingErrorRetry);
+        // Generate identifier per-acquire if not provided
+        const identifier = options?.identifier ?? crypto.randomUUID();
+        const acquiredExternally = options?.acquiredExternally ?? false;
+
+        // If acquiredExternally, use refresh to verify ownership instead of acquire
+        const acquired = acquiredExternally
+          ? yield* backing
+              .refresh(key, identifier, ttl, limit, permits)
+              .pipe(withBackingErrorRetry)
+          : yield* backing
+              .tryAcquire(key, identifier, ttl, limit, permits)
+              .pipe(withBackingErrorRetry);
+
         if (!acquired) {
           return Option.none();
         }
 
         // Start keepalive fiber, tied to this scope
-        const keepAliveFiber = yield* Effect.forkScoped(keepAlive(permits));
+        const keepAliveFiber = yield* Effect.forkScoped(
+          keepAlive(identifier, permits)
+        );
 
         // Add finalizer to release permits when scope closes
         yield* Effect.addFinalizer(() =>
           backing
-            .release(key, holderId, permits)
+            .release(key, identifier, permits)
             .pipe(withBackingErrorRetry, Effect.ignore)
         );
 
@@ -305,40 +364,99 @@ export const make = (
 
     // Acquire permits with retry, returns fiber when acquired
     const take = (
-      permits: number
+      permits: number,
+      options?: AcquireOptions
     ): Effect.Effect<
       Fiber.Fiber<never, LockLostError | SemaphoreBackingError>,
       SemaphoreBackingError,
       Scope.Scope
     > =>
       Effect.gen(function* () {
-        const maybeAcquired = yield* tryTake(permits);
-        if (Option.isNone(maybeAcquired)) {
-          return yield* new NotYetAcquiredError();
-        }
-        return maybeAcquired.value;
-      }).pipe(
-        Effect.retry({
-          while: (e) => e._tag === "NotYetAcquiredError",
-          schedule: Schedule.spaced(acquireRetryInterval),
-        }),
-        Effect.catchTag("NotYetAcquiredError", () =>
-          Effect.dieMessage(
-            "Invariant violated: `take` should never return `NotYetAcquiredError` " +
-              "since it should be caught by the retry which should retry forever until permits are acquired"
+        // Generate identifier once for all retry attempts (outside the retry loop)
+        const identifier = options?.identifier ?? crypto.randomUUID();
+        const resolvedOptions: AcquireOptions = {
+          identifier,
+          acquiredExternally: options?.acquiredExternally,
+        };
+
+        // We use a semaphore to ensure that only one acquire attempt is made at a time.
+        // With `withPermitsIfAvailable`, if both the poll-based and push-based attempts "trigger" at the same time,
+        // one will succeed and the other will simple be a no-op.
+        const acquireSemaphore = yield* Effect.makeSemaphore(1);
+
+        const pushBasedAcquireEnabled = backing.onPermitsReleased
+          ? true
+          : false;
+
+        const pollBasedAcquire = Effect.gen(function* () {
+          const maybeAcquired = yield* tryTake(permits, resolvedOptions).pipe(
+            // only apply the semaphore if push-based acquire is supported
+            pushBasedAcquireEnabled
+              ? Function.compose(
+                  acquireSemaphore.withPermitsIfAvailable(1),
+                  Effect.map(Option.flatten)
+                )
+              : Function.identity
+          );
+          if (Option.isNone(maybeAcquired)) {
+            return yield* new NotYetAcquiredError();
+          }
+          return maybeAcquired.value;
+        }).pipe(
+          Effect.retry({
+            while: (e) => e._tag === "NotYetAcquiredError",
+            schedule: acquireRetryPolicy,
+          }),
+          Effect.catchTag("NotYetAcquiredError", () =>
+            Effect.dieMessage(
+              "Invariant violated: `take` should never return `NotYetAcquiredError` " +
+                "since it should be caught by the retry which should retry forever until permits are acquired"
+            )
           )
-        )
-      );
+        );
+
+        if (!pushBasedAcquireEnabled) {
+          return yield* pollBasedAcquire;
+        }
+
+        // Push-based acquire: run both poll-based and push-based acquire in parallel, and return the first one to complete
+        const pushBasedAcquire = backing.onPermitsReleased
+          ? Effect.gen(function* () {
+              if (!backing.onPermitsReleased) {
+                // SAFETY: We know that onPermitsReleased is provided because we checked it above
+                return yield* Effect.dieMessage(
+                  "Invariant violated: `onPermitsReleased` is not provided"
+                );
+              }
+              return yield* backing.onPermitsReleased(key).pipe(
+                Stream.runFoldWhileEffect(
+                  Option.none<
+                    Fiber.Fiber<never, LockLostError | SemaphoreBackingError>
+                  >(),
+                  Option.isNone, // keep folding while we haven't acquired
+                  () =>
+                    tryTake(permits, resolvedOptions).pipe(
+                      acquireSemaphore.withPermitsIfAvailable(1),
+                      Effect.map(Option.flatten)
+                    )
+                ),
+                Effect.map(Option.getOrThrow)
+              );
+            })
+          : Effect.never;
+
+        return yield* Effect.race(pollBasedAcquire, pushBasedAcquire);
+      });
 
     // Convenience: acquire permits, run effect, release when done
     const withPermits =
-      (permits: number) =>
+      (permits: number, options?: AcquireOptions) =>
       <A, E, R>(
         effect: Effect.Effect<A, E, R>
       ): Effect.Effect<A, E | LockLostError | SemaphoreBackingError, R> =>
         Effect.scoped(
           Effect.gen(function* () {
-            const keepAliveFiber = yield* take(permits);
+            const keepAliveFiber = yield* take(permits, options);
 
             return yield* Effect.raceFirst(effect, Fiber.join(keepAliveFiber));
           })
@@ -346,7 +464,7 @@ export const make = (
 
     // Convenience: try to acquire permits, run effect if successful
     const withPermitsIfAvailable =
-      (permits: number) =>
+      (permits: number, options?: AcquireOptions) =>
       <A, E, R>(
         effect: Effect.Effect<A, E, R>
       ): Effect.Effect<
@@ -356,7 +474,7 @@ export const make = (
       > =>
         Effect.scoped(
           Effect.gen(function* () {
-            const maybeAcquired = yield* tryTake(permits);
+            const maybeAcquired = yield* tryTake(permits, options);
             if (Option.isNone(maybeAcquired)) {
               return Option.none();
             }

package/src/RedisBacking.ts

@@ -1,4 +1,4 @@
-import { Duration, Effect, Layer } from "effect";
+import { Duration, Effect, Layer, Schedule, Stream } from "effect";
 import { Redis } from "ioredis";
 import {
   DistributedSemaphoreBacking,
@@ -54,26 +54,37 @@ end
 /**
  * Lua script for atomic release.
  *
- * Removes all permits held by this holder.
+ * Removes all permits held by this holder and optionally publishes a notification.
  *
  * Arguments:
  * - KEYS[1]: the semaphore key
+ * - KEYS[2]: the release notification channel
  * - ARGV[1]: permits to release
  * - ARGV[2]: holderId
+ * - ARGV[3]: shouldPublish (1 = publish, 0 = don't publish)
  *
  * Returns the number of permits released.
  */
 const RELEASE_SCRIPT = `
 local key = KEYS[1]
+local channel = KEYS[2]
 local permits = tonumber(ARGV[1])
 local holderId = ARGV[2]
+local shouldPublish = tonumber(ARGV[3]) == 1
 local args = {}
 
 for i = 0, permits - 1 do
   table.insert(args, holderId .. '_' .. i)
 end
 
-return redis.call('zrem', key, unpack(args))
+local released = redis.call('zrem', key, unpack(args))
+
+-- Notify waiters that permits may be available
+if released > 0 and shouldPublish then
+  redis.call('publish', channel, released)
+end
+
+return released
 `;
 
 /**
@@ -142,6 +153,33 @@ redis.call('zremrangebyscore', key, '-inf', expiredTimestamp)
 return redis.call('zcard', key)
 `;
 
+export interface RedisBackingOptions {
+  /**
+   * Prefix for all keys in Redis.
+   * @default "semaphore:"
+   */
+  readonly keyPrefix?: string;
+
+  /**
+   * Enable push-based acquisition using Redis pub/sub.
+   *
+   * When enabled, waiters subscribe to a channel and get notified immediately
+   * when permits are released, instead of polling. This reduces latency and
+   * load on Redis.
+   *
+   * Requires an additional Redis connection per waiting semaphore.
+   *
+   * @default true
+   */
+  readonly pushBasedAcquireEnabled?: boolean;
+
+  /**
+   * How often to retry the stream of notifications when permits are released.
+   * @default Schedule.forever
+   */
+  readonly pushStreamRetrySchedule?: Schedule.Schedule<void>;
+}
+
 /**
  * Create a Redis-backed distributed semaphore backing layer.
  *
@@ -151,13 +189,18 @@ return redis.call('zcard', key)
  * For multi-instance Redis, consider implementing a Redlock-based backing.
  *
  * @param redis - An ioredis client instance (single instance, not cluster)
- * @param keyPrefix - Optional prefix for all keys (default: "dsem:")
+ * @param options - Configuration options
  */
 export const layer = (
   redis: Redis,
-  keyPrefix = "dsem:"
+  options: RedisBackingOptions = {}
 ): Layer.Layer<DistributedSemaphoreBacking> => {
+  const keyPrefix = options.keyPrefix ?? "semaphore:";
+  const pushBasedAcquireEnabled = options.pushBasedAcquireEnabled ?? true;
+  const pushStreamRetrySchedule =
+    options.pushStreamRetrySchedule ?? Schedule.forever.pipe(Schedule.asVoid);
   const prefixKey = (key: string) => `${keyPrefix}${key}`;
+  const releaseChannel = (key: string) => `${keyPrefix}${key}:released`;
 
   const tryAcquire = (
     key: string,
@@ -194,10 +237,12 @@ export const layer = (
       try: async () => {
         const result = await redis.eval(
           RELEASE_SCRIPT,
-          1,
+          2,
           prefixKey(key),
+          releaseChannel(key),
           permits.toString(),
-          holderId
+          holderId,
+          pushBasedAcquireEnabled ? "1" : "0"
         );
         return result as number;
       },
@@ -251,10 +296,55 @@ export const layer = (
         new SemaphoreBackingError({ operation: "getCount", cause }),
     });
 
+  // Stream that emits when permits are released on a given key.
+  // Uses Redis pub/sub with a dedicated subscriber connection.
+  const onPermitsReleased = (key: string): Stream.Stream<void> =>
+    Stream.asyncPush<void, SemaphoreBackingError>((emit) => {
+      const channel = releaseChannel(key);
+
+      return Effect.acquireRelease(
+        Effect.gen(function* () {
+          // Create a dedicated subscriber connection
+          const subscriber = redis.duplicate();
+
+          // Set up message handler before subscribing
+          const messageHandler = (ch: string, _message: string) => {
+            if (ch === channel) {
+              emit.single(void 0);
+            }
+          };
+          subscriber.on("message", messageHandler);
+
+          // Subscribe to the channel
+          yield* Effect.tryPromise({
+            try: () => subscriber.subscribe(channel),
+            catch: (cause) =>
+              new SemaphoreBackingError({ operation: "subscribe", cause }),
+          });
+
+          return { subscriber, messageHandler };
+        }),
+        ({ subscriber, messageHandler }) =>
+          Effect.sync(() => {
+            subscriber.off("message", messageHandler);
+            subscriber.unsubscribe(channel);
+            subscriber.disconnect();
+          })
+      );
+    }).pipe(
+      Stream.retry(pushStreamRetrySchedule),
+      Stream.catchTag("SemaphoreBackingError", () =>
+        Stream.dieMessage(
+          "Invariant violated: `onPermitsReleased` should never error because it should be retried forever"
+        )
+      )
+    );
+
   return Layer.succeed(DistributedSemaphoreBacking, {
     tryAcquire,
     release,
     refresh,
     getCount,
+    onPermitsReleased: pushBasedAcquireEnabled ? onPermitsReleased : undefined,
   });
 };