.TH "Spacetime" 3o 2020-09-04 OCamldoc "OCaml library"
.SH NAME
Spacetime \- Profiling of a program's space behaviour over time.
.SH Module
Module   Spacetime
.SH Documentation
.sp
Module
.BI "Spacetime"
 : 
.B sig end

.sp
Profiling of a program\&'s space behaviour over time\&.
Currently only supported on x86\-64 platforms running 64\-bit code\&.
.sp
To use the functions in this module you must:
.sp
\-configure the compiler with "\-spacetime";
.sp
\-compile to native code\&.
Without these conditions being satisfied the functions in this module
will have no effect\&.

Instead of manually taking profiling heap snapshots with this module it is
possible to use an automatic snapshot facility that writes profiling
information at fixed intervals to a file\&. To enable this, all that needs to
be done is to 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 
.ft B
exit
.ft R
, with whatever exit code, rather than being
abnormally terminated by a signal) so that the snapshot file is
correctly completed\&.
.sp
When using the 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\&.  This may be customised by setting the OCAML_SPACETIME_SNAPSHOT_DIR
environment variable to the name of the desired directory\&.
.sp
If using automatic snapshots the presence of the
.ft B
save_event_for_automatic_snapshots
.ft R
function, below, should be noted\&.
.sp
The functions in this module are thread safe\&.
.sp
For functions to decode the information recorded by the profiler,
see the Spacetime offline library in otherlibs/\&.

.sp

.sp
.sp

.I val enabled 
: 
.B bool
.sp

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

.sp
.I module Series : 
.B sig end

.sp

.sp
.I module Snapshot : 
.B sig end

.sp

.sp

.I val save_event_for_automatic_snapshots 
: 
.B event_name:string -> unit
.sp
Like 
.ft B
Spacetime\&.Series\&.save_event
.ft R
, but writes to the automatic snapshot file\&.
This function is a no\-op if OCAML_SPACETIME_INTERVAL was not set\&.

.sp