Spacetime(3)

💖 NAME 💖

Spacetime — profiling of a program's space behaviour over time. The manual page title is Spacetime(3), and it's from the OCaml library, bestie — folding that header info in right here so you know what you're reading. 🫶

🧚 Module 🧚

Module Spacetime

✨ Documentation ✨

Okay so here's the module signature, literally in its natural habitat:

Module Spacetime
 : sig end

Spacetime is all about profiling of a program's space behaviour over time. Currently, it's only supported on x86-64 platforms running 64-bit code — no cap.

To use the functions in this module you must:

• -configure the compiler with "-spacetime";
• -compile to native code.

Without these conditions being satisfied, the functions in this module will have no effect. Like, zero. 💀

---

Instead of manually taking profiling heap snapshots with this module, there's an automatic snapshot facility that writes profiling information at fixed intervals to a file. To enable it, all you gotta do is build the relevant program using a compiler configured with -spacetime, and set the environment variable OCAML_SPACETIME_INTERVAL to an integer number of milliseconds giving the interval between profiling heap snapshots. This interval should not be made excessively small relative to the running time of the program — a typical interval to start with might be 1/100 of the running time of the program. The program must exit "normally" (i.e. by calling exit, with whatever exit code, rather than being abnormally terminated by a signal) so that the snapshot file is correctly completed. Periodt. 💅

When using automatic snapshot mode, the profiling output is written to a file called "spacetime-<pid>", where <pid> is the process ID of the program. (If the program forks and continues executing, then multiple files may be produced with different pid numbers.) The profiling output is by default written to the current working directory when the program starts. You can customize this by setting the OCAML_SPACETIME_SNAPSHOT_DIR environment variable to the name of the desired directory. 🌸

If you're using automatic snapshots, note the presence of the save_event_for_automatic_snapshots function below. 👀

The functions in this module are thread safe. 🧵✨

For functions to decode the information recorded by the profiler, see the Spacetime offline library in otherlibs/.

Now the values and modules, bestie:

val enabled : bool

enabled is true if the compiler is configured with spacetime and false otherwise.

module Series : sig end

module Snapshot : sig end

val save_event_for_automatic_snapshots : event_name:string -> unit

Like Spacetime.Series.save_event, but writes to the automatic snapshot file. This function is a no-op if OCAML_SPACETIME_INTERVAL was not set.

---

This iconic little page came from OCamldoc, dated 2022-03-11 — and yes, it's the Spacetime(3) manual page. Slay. 💖