Show raw api
{
"functions": [
{
"name": "acquireLock",
"desc": "Attempts to acquire a distributed lock for the specified key.\n\nManages the lock acquisition process, including retries with exponential\nbackoff, setting up the background refresh loop, and providing a LockHandle\non success.",
"params": [
{
"name": "params",
"desc": "Configuration for the lock acquisition.",
"lua_type": "AcquireLockParams"
}
],
"returns": [
{
"desc": "Resolves with a LockHandle if the lock is acquired successfully.",
"lua_type": "Promise<LockHandle>"
}
],
"function_type": "static",
"errors": [
{
"lua_type": "Rejects if the lock cannot be acquired within the specified duration/attempts, or if other MemoryStore errors occur.",
"desc": ""
}
],
"source": {
"line": 84,
"path": "src/Locks.luau"
}
},
{
"name": "transitionTo",
"desc": "Helper function to update the internal lock status and log the transition.\n\t",
"params": [
{
"name": "newStatus",
"desc": "The new status to set.",
"lua_type": "LockStatus"
}
],
"returns": [],
"function_type": "static",
"private": true,
"source": {
"line": 110,
"path": "src/Locks.luau"
}
},
{
"name": "spawnExpiryCallbacks",
"desc": "Invokes all registered `onLockLost` callbacks.\nCalled when the local expiry timer (`expiryThread`) fires or when refresh fails.\n\t",
"params": [],
"returns": [],
"function_type": "static",
"private": true,
"source": {
"line": 121,
"path": "src/Locks.luau"
}
},
{
"name": "tryUpdate",
"desc": "Attempts to update the lock key in MemoryStore using UpdateAsync.\nThis is used for initial acquisition, refresh, and release (with ttl=0).\n\nThe transform function ensures atomicity:\n- If the key doesn't exist (`otherLockId == nil`), set it to our `lockId`.\n- If the key exists and holds our `lockId`, update the TTL (refresh).\n- If the key exists and holds a different `lockId`, do nothing (fail acquisition/refresh).\n\nAlso manages the local expiry timer (`expiryThread`) based on successful updates.\n\n\t",
"params": [
{
"name": "ttl",
"desc": "The Time-To-Live in seconds for the UpdateAsync call.",
"lua_type": "number"
}
],
"returns": [
{
"desc": "Handle containing the promise and cancel function from `hashMapRetry`.",
"lua_type": "Types.RetryHandle<Promise<any>>"
}
],
"function_type": "static",
"private": true,
"source": {
"line": 148,
"path": "src/Locks.luau"
}
},
{
"name": "release",
"desc": "Releases the lock. Stops refresh/expiry timers and attempts to clear the\nlock in MemoryStore by setting TTL to 0.\n\n\t",
"params": [],
"returns": [
{
"desc": "Resolves when the release process is complete.",
"lua_type": "Promise"
}
],
"function_type": "static",
"private": true,
"source": {
"line": 201,
"path": "src/Locks.luau"
}
},
{
"name": "waitForLock",
"desc": "Main loop for attempting to acquire the lock initially.\nUses `tryUpdate` with exponential backoff.\n\n\t",
"params": [],
"returns": [
{
"desc": "Resolves when the lock is acquired, rejects if timeout occurs.",
"lua_type": "Promise"
}
],
"function_type": "static",
"private": true,
"source": {
"line": 249,
"path": "src/Locks.luau"
}
},
{
"name": "setupLockRefresh",
"desc": "Starts the background loop responsible for periodically refreshing the lock TTL.\n\t",
"params": [],
"returns": [],
"function_type": "static",
"private": true,
"source": {
"line": 338,
"path": "src/Locks.luau"
}
},
{
"name": "probeLockActive",
"desc": "Checks if a lock key currently exists in MemoryStore without attempting to acquire it.\nUseful for determining if another process likely holds the lock.\n\nNote: This is a point-in-time check and doesn't guarantee the lock state won't\nchange immediately after the check completes.",
"params": [
{
"name": "params",
"desc": "Parameters for probing the lock.",
"lua_type": "ProbeLockActiveParams"
}
],
"returns": [
{
"desc": "Resolves with true if the lock key exists, false otherwise.",
"lua_type": "Promise<boolean>"
}
],
"function_type": "static",
"source": {
"line": 461,
"path": "src/Locks.luau"
}
}
],
"properties": [],
"types": [
{
"name": "LockStatus",
"desc": "Possible states of the lock acquisition and holding process.",
"lua_type": "\"acquiring\" | \"held\" | \"released\"",
"tags": [
"enum"
],
"private": true,
"source": {
"line": 38,
"path": "src/Locks.luau"
}
},
{
"name": "LockHandle",
"desc": "Represents an acquired lock handle, providing methods to interact with the lock.",
"fields": [
{
"name": "release",
"lua_type": "() -> Promise",
"desc": "Releases the lock immediately. Stops the refresh loop and attempts to clear the lock key in MemoryStore (by setting TTL to 0). Resolves when the release attempt is complete."
},
{
"name": "isLocked",
"lua_type": "() -> boolean",
"desc": "Checks if the lock is currently considered held locally. This checks both the internal status and compares the last confirmed expiry time (from MemoryStore) against the current local time. True if the lock is believed to be held."
},
{
"name": "onLockLost",
"lua_type": "(() -> ()) -> (() -> ())",
"desc": "Registers a callback function to be invoked if the lock is lost unexpectedly (e.g., refresh fails, TTL expires). Returns a function to disconnect/unregister the callback."
}
],
"source": {
"line": 49,
"path": "src/Locks.luau"
}
},
{
"name": "AcquireLockParams",
"desc": "Parameters for acquiring a lock.",
"fields": [
{
"name": "storeContext",
"lua_type": "Types.StoreContext<any>",
"desc": "Shared store context containing logger and MemoryStoreHashMap instance."
},
{
"name": "key",
"lua_type": "string",
"desc": "The unique key identifying the resource to be locked."
},
{
"name": "duration",
"lua_type": "number",
"desc": "The duration (TTL) in seconds for which the lock should be held/refreshed."
},
{
"name": "refreshInterval",
"lua_type": "number",
"desc": "The interval in seconds at which the lock refresh should be attempted."
}
],
"source": {
"line": 65,
"path": "src/Locks.luau"
}
},
{
"name": "ProbeLockActiveParams",
"desc": "Parameters for probing if a lock is active.",
"fields": [
{
"name": "storeContext",
"lua_type": "Types.StoreContext<any>",
"desc": "Shared store context containing logger and MemoryStoreHashMap instance."
},
{
"name": "key",
"lua_type": "string",
"desc": "The unique key identifying the resource to be locked."
}
],
"source": {
"line": 445,
"path": "src/Locks.luau"
}
}
],
"name": "Locks",
"desc": "Implements a distributed locking mechanism using Roblox's MemoryStoreService.\nThis allows coordinating access to shared resources (like DataStore keys)\nacross different game servers or instances.\n\nThe locking strategy involves:\n- Attempting to atomically acquire a lock using `MemoryStoreService:UpdateAsync`.\n- Setting a Time-To-Live (TTL) on the lock key in MemoryStore.\n- Periodically refreshing the lock's TTL in a background task to maintain ownership.\n- Providing a mechanism (`onLockLost`) to notify the holder if the lock refresh fails\n or the lock expires unexpectedly.\n\nThis ensures that typically only one process holds the lock for a given key at a time.",
"private": true,
"source": {
"line": 18,
"path": "src/Locks.luau"
}
}