Skip to main content

PlayerDataStoreHandle

This item only works when running on the server. Server

A borrowed DataStore for a player, and the obligation to put it back.

Opening a store for a player who is not in this server takes their session lock, which kicks them from wherever they were playing. Until that lock is dropped again they cannot rejoin, so releasing it is the part that matters -- and a release the caller has to remember to perform is one that eventually gets missed on an error path.

Handing back a handle makes it a [Maid]-shaped obligation instead: give it to a maid, or destroy it, and the session is released once nothing is using it. Destroying twice is safe.

Handles are counted, so three systems loading the same player each get their own and the session survives until the last one is destroyed.

A player in this server is not represented by a handle -- their session is owned by the join and leave path, which reaches removal from several directions a handle could not model safely. So destroying a handle never closes a live player's session; it only releases one this tooling opened on behalf of someone absent. 

local handle = manager:PromiseDataStoreHandle(userId):Yield()
local data = handle:GetDataStore():LoadAll({}):Yield()
handle:Destroy()

Functions​

new​

</>
PlayerDataStoreHandle.new(
dataStore: DataStore,
release: (() → ())?--

invoked on destroy, when this handle is the one that borrowed the store

) → PlayerDataStoreHandle

Constructs a new handle over a datastore.

isPlayerDataStoreHandle​

</>
PlayerDataStoreHandle.isPlayerDataStoreHandle(value: any) → boolean

Returns whether the value is a handle.

GetDataStore​

</>
PlayerDataStoreHandle.GetDataStore(self: PlayerDataStoreHandle) → DataStore

Returns the datastore this handle holds. Errors once destroyed, since the session behind it may already be closed.

Destroy​

</>
PlayerDataStoreHandle.Destroy(self: PlayerDataStoreHandle) → ()

Drops this handle's reference to the session. The session itself is released once no handle and no player in this server is still holding it.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new handle over a datastore.",
            "params": [
                {
                    "name": "dataStore",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "release",
                    "desc": "invoked on destroy, when this handle is the one that borrowed the store",
                    "lua_type": "(() -> ())?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "PlayerDataStoreHandle"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 54,
                "path": "src/datastore/src/Server/PlayerDataStoreHandle.lua"
            }
        },
        {
            "name": "isPlayerDataStoreHandle",
            "desc": "Returns whether the value is a handle.",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 69,
                "path": "src/datastore/src/Server/PlayerDataStoreHandle.lua"
            }
        },
        {
            "name": "GetDataStore",
            "desc": "Returns the datastore this handle holds. Errors once destroyed, since the session behind it may\nalready be closed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "PlayerDataStoreHandle"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 79,
                "path": "src/datastore/src/Server/PlayerDataStoreHandle.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Drops this handle's reference to the session. The session itself is released once no handle and\nno player in this server is still holding it.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "PlayerDataStoreHandle"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 92,
                "path": "src/datastore/src/Server/PlayerDataStoreHandle.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PlayerDataStoreHandle",
    "desc": "A borrowed [DataStore] for a player, and the obligation to put it back.\n\nOpening a store for a player who is not in this server takes their session lock, which kicks them\nfrom wherever they were playing. Until that lock is dropped again they cannot rejoin, so releasing\nit is the part that matters -- and a release the caller has to remember to perform is one that\neventually gets missed on an error path.\n\nHanding back a handle makes it a [Maid]-shaped obligation instead: give it to a maid, or destroy\nit, and the session is released once nothing is using it. Destroying twice is safe.\n\nHandles are counted, so three systems loading the same player each get their own and the session\nsurvives until the last one is destroyed.\n\nA player in this server is not represented by a handle -- their session is owned by the join and\nleave path, which reaches removal from several directions a handle could not model safely. So\ndestroying a handle never closes a live player's session; it only releases one this tooling\nopened on behalf of someone absent.\n\n```lua\nlocal handle = manager:PromiseDataStoreHandle(userId):Yield()\nlocal data = handle:GetDataStore():LoadAll({}):Yield()\nhandle:Destroy()\n```",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 30,
        "path": "src/datastore/src/Server/PlayerDataStoreHandle.lua"
    }
}