Gleam FFI Atom Handling vs BEAM Non-GC Atom Table Boundary

Answer

From within a pure Gleam program you cannot directly query the BEAM atom table; the only reliable method is to call Erlang OTP diagnostics via FFI. The steps are:

1. Expose an Erlang BIF such as erlang:system_info/1 or erlang:atom_info/1 through a Gleam FFI binding.
2. Call the BIF with the atom key max_atoms (or system_info with atomic option) to obtain the current atom count and the configured limit.
3. Compare the returned count with the limit; if the count approaches the limit, log a warning or trigger a supervision restart.
4. Optionally, periodically sample the atom count in a background process and expose the metric via a Gleam server or telemetry endpoint.

Likely explanation vs confirmed facts

Likely: The BEAM atom table is global, not garbage‑collected, and its size is bounded by a configurable max_atoms setting that varies by OTP version and emulator flags.

Confirmed: Gleam’s standard library does not expose live atom‑table size; only the number of Atom values created or received by the Gleam code can be counted, which is blind to atoms generated by Erlang libraries or the VM itself. The compiler cannot infer a finite bound for atoms produced at runtime, and no standard build tool emits warnings about unbounded atom generation.

Compiler warnings

No built‑in Gleam or Mix tooling currently checks FFI signatures for potential unbounded atom creation. A custom lint could flag functions whose FFI arguments or results are of type Atom derived from untrusted strings, but such a warning would be heuristic and not guarantee safety.

Safe atom interning / reuse patterns

Documented Erlang practice is to limit the atom domain to a fixed set and reuse existing atoms via an application‑level pool. In Gleam you can:

• Define a known set of atoms (e.g., via defatom/1 or constant modules) and use erlang:atom/2 to look up or create them, rejecting unknown keys.
• Prefer non‑atom representations such as strings, binaries, or tuples for dynamic keys, map keys, or error tags, and only convert to atoms when the set is bounded.
• When an atom must be created from external input, first check an intern table (e.g., a map of previously seen atoms) and reuse the existing atom instead of creating a new one.

If you need to know whether the atom limit is being approached, confirm the exact max_atoms value in your OTP release; this determines whether the above monitoring steps are sufficient or whether additional safeguards (e.g., limiting dynamic atom creation) are required.