Skip to main content

Pooler

An instance pooler.

Types​

GetMethod​

</>
type GetMethod = "sequential" | "random"

The method that this Pooler should use to retrieve instances. sequential will retrieve them in an ascending order (item 1 -> item n) whilst random will retrieve instances randomly.

ReturnMethod​

</>
type ReturnMethod = "nilParent" | "cframe"

The method that this Pooler should use to return instances. nilParent will set the instance's parent to nil and leave all other properties intact whilst cframe will set the CFrame of the instance to a very long distance away, which is faster for BaseParts and Models with PrimaryPart set. cframe, as such, is only supported if you're pooling BaseParts or Models.

Options​

</>
interface Options {
size: number?--

The number of objects to initialise this pool with. Defaults to 100.

getMethod: GetMethod?--

The get method to use. Defaults to "sequential".

returnMethod: ReturnMethod?--

The return method to use. Defaults to "nilParent".

unsafe: boolean?--

Whether or not the Pooler should skip safety checks. This pretty much means that you're on your own when it comes to doing things properly, but it increases performance. Defaults to false.

exhaustion: boolean?--

Whether or not the pool can be exhausted. When enabled, instances will be removed from the internal pool table and you will have to return them yourself to add them back. Defaults to false.

}

An object that describes any extra options you want to pass when creating a Pooler. All options are not required.

Functions​

new​

Constructor
</>
Pooler.new(
instanceTemplate: T,--

The instance that this Pooler should base its pooled objects on.

opts: Options?--

Any extra options you want to pass.

) → Pooler<T>--

A Pooler instance.

Creates a new Pooler instance.

local pool = Pooler.new(Instance.new("Part"))

Errors

TypeDescription
"cannot create Pooler without an instance template"Occurs when you're attempting to create a Pooler without a template.
"cannot create Pooler with cframe return method if instance template is not a BasePart or Model"Occurs when trying to use the `cframe` ReturnMethod when your template isn't a BasePart or a Model.
"cannot create Pooler with cframe return method if instance template is a Model and it has no PrimaryPart"Occurs when trying to use the `cframe` ReturnMethod when your template is a Model and it has no PrimaryPart.
"cannot use random getMethod with exhaustion enabled"Occurs when you're trying to use the `random` GetMethod with `exhaustion` enabled. `random` is not a valid GetMethod since it might retrieve a nil value.

Get​

</>
Pooler:Get() → T--

An instance.

Gets an instance from the pool.

local pool = Pooler.new(Instance.new("Part"))

local instance = pool:Get()

Errors

TypeDescription
"attempt to use destroyed Pooler instance"Occurs when this Pooler has been destroyed and you are trying to call methods on it.
"pool exhausted"Occurs when the pool has been exhausted of all of it's instances and exhaustion is enabled.

Wait​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
Pooler:Wait() → T--

An instance.

Gets an instance from the pool. If the pool is exhausted, it will wait until an instance is available before returning.

local pool = Pooler.new(Instance.new("Part"))

local instance = pool:Wait()

Errors

TypeDescription
"attempt to use destroyed Pooler instance"Occurs when this Pooler has been destroyed and you are trying to call methods on it.

Return​

</>
Pooler:Return(
instance: T--

The instance to return.

) → ()

Returns an instance to the pool.

local pool = Pooler.new(Instance.new("Part"))

local instance = pool:Get()

pool:Return(instance)

Errors

TypeDescription
"attempt to use destroyed Pooler instance"Occurs when this Pooler has been destroyed and you are trying to call methods on it.
"attempt to return instance not part of this pool"Occurs when you attempt to return an instance that wasn't a part of this pool to begin with.
"instance is not a BasePart or Model but it's using the cframe return method"Occurs when the instance you're returning is not a BasePart or a Model, but you're somehow using the CFrame return method. If safety is enabled and you haven't been tampering with the internals, this is almost always a bug and should be reported.

Size​

</>
Pooler:Size() → number--

The size of the pool.

Get the current size of the pool.

local pool = Pooler.new(Instance.new("Part"))

local size = pool:Size()

Resize​

</>
Pooler:Resize(
newSize: number--

The new size the pool should be.

) → ()

Resizes the pool.

local pool = Pooler.new(Instance.new("Part"))

pool:Resize(1000)

Errors

TypeDescription
"attempt to use destroyed Pooler instance"Occurs when this Pooler has been destroyed and you are trying to call methods on it.

Destroy​

</>
Pooler:Destroy() → ()

Destroys this Pooler and destroys all instances associated with the pool.

local pool = Pooler.new(Instance.new("Part"))

pool:Destroy()
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new Pooler instance.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n```",
            "params": [
                {
                    "name": "instanceTemplate",
                    "desc": "The instance that this Pooler should base its pooled objects on.",
                    "lua_type": "T"
                },
                {
                    "name": "opts",
                    "desc": "Any extra options you want to pass.",
                    "lua_type": "Options?"
                }
            ],
            "returns": [
                {
                    "desc": "A Pooler instance.",
                    "lua_type": "Pooler<T>"
                }
            ],
            "function_type": "static",
            "tags": [
                "Constructor"
            ],
            "errors": [
                {
                    "lua_type": "\"cannot create Pooler without an instance template\"",
                    "desc": "Occurs when you're attempting to create a Pooler without a template."
                },
                {
                    "lua_type": "\"cannot create Pooler with cframe return method if instance template is not a BasePart or Model\"",
                    "desc": "Occurs when trying to use the `cframe` ReturnMethod when your template isn't a BasePart or a Model."
                },
                {
                    "lua_type": "\"cannot create Pooler with cframe return method if instance template is a Model and it has no PrimaryPart\"",
                    "desc": "Occurs when trying to use the `cframe` ReturnMethod when your template is a Model and it has no PrimaryPart."
                },
                {
                    "lua_type": "\"cannot use random getMethod with exhaustion enabled\"",
                    "desc": "Occurs when you're trying to use the `random` GetMethod with `exhaustion` enabled. `random` is not a valid GetMethod since it might retrieve a nil value."
                }
            ],
            "source": {
                "line": 84,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Get",
            "desc": "Gets an instance from the pool.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n\nlocal instance = pool:Get()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "An instance.",
                    "lua_type": "T"
                }
            ],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"attempt to use destroyed Pooler instance\"",
                    "desc": "Occurs when this Pooler has been destroyed and you are trying to call methods on it."
                },
                {
                    "lua_type": "\"pool exhausted\"",
                    "desc": "Occurs when the pool has been exhausted of all of it's instances and exhaustion is enabled."
                }
            ],
            "source": {
                "line": 174,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Wait",
            "desc": "Gets an instance from the pool. If the pool is exhausted, it will wait until an instance is available before returning.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n\nlocal instance = pool:Wait()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "An instance.",
                    "lua_type": "T"
                }
            ],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"attempt to use destroyed Pooler instance\"",
                    "desc": "Occurs when this Pooler has been destroyed and you are trying to call methods on it."
                }
            ],
            "yields": true,
            "source": {
                "line": 227,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Return",
            "desc": "Returns an instance to the pool.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n\nlocal instance = pool:Get()\n\npool:Return(instance)\n```",
            "params": [
                {
                    "name": "instance",
                    "desc": "The instance to return.",
                    "lua_type": "T"
                }
            ],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"attempt to use destroyed Pooler instance\"",
                    "desc": "Occurs when this Pooler has been destroyed and you are trying to call methods on it."
                },
                {
                    "lua_type": "\"attempt to return instance not part of this pool\"",
                    "desc": "Occurs when you attempt to return an instance that wasn't a part of this pool to begin with."
                },
                {
                    "lua_type": "\"instance is not a BasePart or Model but it's using the cframe return method\"",
                    "desc": "Occurs when the instance you're returning is not a BasePart or a Model, but you're somehow using the CFrame return method. If safety is enabled and you haven't been tampering with the internals, this is almost always a bug and should be reported."
                }
            ],
            "source": {
                "line": 260,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Size",
            "desc": "Get the current size of the pool.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n\nlocal size = pool:Size()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "The size of the pool.",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 305,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Resize",
            "desc": "Resizes the pool.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n\npool:Resize(1000)\n```",
            "params": [
                {
                    "name": "newSize",
                    "desc": "The new size the pool should be.",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"attempt to use destroyed Pooler instance\"",
                    "desc": "Occurs when this Pooler has been destroyed and you are trying to call methods on it."
                }
            ],
            "source": {
                "line": 322,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys this Pooler and destroys all instances associated with the pool.\n\n```lua\nlocal pool = Pooler.new(Instance.new(\"Part\"))\n\npool:Destroy()\n```",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 351,
                "path": "lib/init.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "GetMethod",
            "desc": "The method that this Pooler should use to retrieve instances. `sequential` will retrieve them in an ascending order (item 1 -> item `n`)\nwhilst `random` will retrieve instances randomly.",
            "lua_type": "\"sequential\" | \"random\"",
            "source": {
                "line": 33,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "ReturnMethod",
            "desc": "The method that this Pooler should use to return instances. `nilParent` will set the instance's parent to `nil` and leave all other\nproperties intact whilst `cframe` will set the CFrame of the instance to a very long distance away, which is faster for BaseParts\nand Models with PrimaryPart set. `cframe`, as such, is only supported if you're pooling BaseParts or Models.",
            "lua_type": "\"nilParent\" | \"cframe\"",
            "source": {
                "line": 43,
                "path": "lib/init.lua"
            }
        },
        {
            "name": "Options",
            "desc": "An object that describes any extra options you want to pass when creating a Pooler. All options are not required.",
            "fields": [
                {
                    "name": "size",
                    "lua_type": "number?",
                    "desc": "The number of objects to initialise this pool with. Defaults to 100."
                },
                {
                    "name": "getMethod",
                    "lua_type": "GetMethod?",
                    "desc": "The get method to use. Defaults to \"sequential\"."
                },
                {
                    "name": "returnMethod",
                    "lua_type": "ReturnMethod?",
                    "desc": "The return method to use. Defaults to \"nilParent\"."
                },
                {
                    "name": "unsafe",
                    "lua_type": "boolean?",
                    "desc": "Whether or not the Pooler should skip safety checks. This pretty much means that you're on your own when it comes to doing things properly, but it increases performance. Defaults to false."
                },
                {
                    "name": "exhaustion",
                    "lua_type": "boolean?",
                    "desc": "Whether or not the pool can be exhausted. When enabled, instances will be removed from the internal pool table and you will have to return them yourself to add them back. Defaults to false."
                }
            ],
            "source": {
                "line": 57,
                "path": "lib/init.lua"
            }
        }
    ],
    "name": "Pooler",
    "desc": "An instance pooler.",
    "source": {
        "line": 12,
        "path": "lib/init.lua"
    }
}