infoThis version ships no README. Showing the README from v0.1.2, mirrored from wally.

CoreFinder

Estimates the number of parallel execution cores available to Roblox Actors at runtime.

Why

Knowing how many CPU cores are available lets you split work into the right number of parallel tasks. Creating more tasks than cores forces some to wait; creating fewer leaves cores idle. The best performance comes when the number of tasks matches the number of cores.

Example

Consider a task that takes 10 seconds on a machine with 3 available cores:

Splitting into exactly 3 subtasks — matching the available cores — completes the work in about 3.3 s instead of 5 s (ignoring overhead).

How It Works

CoreFinder dispatches parallel Actor workers that deliberately occupy execution cores for a fixed spin window. Each worker atomically increments a SharedTable counter, then busy-spins for the duration of the window to hold its core. The number of workers that successfully run within the same window reflects how many workers executed concurrently.

The search space starts small and doubles exponentially until a stable count is found (i.e. fewer actors respond than were dispatched) or a maximum pool size is reached, indicating that available parallelism has been saturated.

Installation

Wally

[dependencies]
CoreFinder = "akari_yn/corefinder@0.1.0"

Manual

Drop the CoreFinder folder into your project so it is accessible via require(). The module is self-contained — no external dependencies are needed.

The folder structure should look like:

CoreFinder/
├── init.luau              -- Module source & worker logic
├── Requirer.client.luau   -- Requires init.luau on the client so the module
│                          -- can clone itself to create worker Actors
└── Requirer.server.luau   -- Requires init.luau on the server so the module
                           -- can clone itself to create worker Actors

Usage

local GetCoreCount = require(path.to.CoreFinder)

local cores = GetCoreCount()       -- uses default 0.1s spin window
print("Detected", cores, "core(s)")

-- or with a custom spin window for more accuracy
local cores = GetCoreCount(0.5)

Parameters

Returns

number — Estimated number of parallel execution cores (lower bound).

Tips

• Longer spin windows improve accuracy when other scripts may temporarily occupy execution cores (e.g. during startup/shutdown) at the cost of higher detection latency.
• Results represent a lower bound on available parallelism and may be reduced by system load or engine limits.
• You can run the function multiple times and take the maximum for a more reliable estimate.

Default Search Sizes

The search pool caps at 1024 actors to prevent runaway allocation.

License

See LICENSE.md.