Interface IMachineMemory<T>

Manages machine state memory operations with optimistic locking strategy. Implements a "fail fast on acquire, be tolerant on release" approach for resource management.

interface IMachineMemory<T> {
    lock(id: string): Promise<boolean>;
    read(id: string): Promise<null | T>;
    unlock(id: string): Promise<boolean>;
    write(id: string, data: T, prevData: null | T): Promise<void>;
}

Type Parameters

  • T extends Record<string, any>

    Structure of stored data

Implemented by

Methods

lock read unlock write

Methods

lock

  • lock(id): Promise<boolean>

  • Acquires execution lock for machine ID (event.subject). Should implement reasonable retries with backoff for transient lock conflicts. Must fail fast after retry attempts exhausted - no long polling.

    Parameters

    • id: string

      Machine ID

    Returns Promise<boolean>

    True if lock acquired successfully

    Throws

    Error if lock operation fails (not same as lock denial)

read

  • read(id): Promise<null | T>

  • Gets state data for machine ID (event.subject). Should implement minimal retries (e.g. 2-3 attempts) with backoff for transient failures. Must distinguish between:

    • No data exists: Returns null (normal case for new machines)
    • Operation failed: Throws error after all retries exhausted

    Retry strategy should be quick with reasonable timeout to avoid blocking:

    • Few retry attempts (2-3)
    • Short backoff delays (e.g. 100ms with exponential backoff)
    • Total operation time under 1s

    Parameters

    • id: string

      Machine ID

    Returns Promise<null | T>

    null if no data exists, T if data found

    Throws

    Error if read operation fails after retries (e.g. connection error, permission denied)

unlock

  • unlock(id): Promise<boolean>

  • Releases execution lock for machine ID (event.subject). Can retry a few times on failure but should not over-engineer. System will eventually recover even if unlock fails.

    Implementation MUST include lock expiry mechanism (TTL):

    • Set reasonable TTL when acquiring lock (e.g. 30s-5m based on execution patterns)
    • Ensure locks auto-expire to prevent deadlocks from unlock failures
    • Consider execution patterns when setting TTL to avoid premature expiry

    Parameters

    • id: string

      Machine ID

    Returns Promise<boolean>

    True if unlocked successfully

write

  • write(id, data, prevData): Promise<void>

  • Saves state data for machine ID (event.subject). Should fail fast - if write fails, throw error immediately. No retry logic as consistency is critical and caller handles failures.

    Parameters

    • id: string

      Machine ID

    • data: T

      State to save

    • prevData: null | T

      The previous snapshot of the data

    Returns Promise<void>

    Throws

    Error if write operation fails

Settings

Member Visibility

On This Page

Methods