1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
(**************************************************************************)
(* *)
(* OCaml *)
(* *)
(* Mark Shinwell and Leo White, Jane Street Europe *)
(* *)
(* Copyright 2015--2016 Jane Street Group LLC *)
(* *)
(* All rights reserved. This file is distributed under the terms of *)
(* the GNU Lesser General Public License version 2.1, with the *)
(* special exception on linking described in the file LICENSE. *)
(* *)
(**************************************************************************)
(** Profiling of a program's space behaviour over time.
Currently only supported on x86-64 platforms running 64-bit code.
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.
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 [exit], with whatever exit code, rather than being
abnormally terminated by a signal) so that the snapshot file is
correctly completed.
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.
If using automatic snapshots the presence of the
[save_event_for_automatic_snapshots] function, below, should be noted.
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/. *)
(** [enabled] is [true] if the compiler is configured with spacetime and [false]
otherwise *)
val enabled : bool
module Series : sig
(** Type representing a file that will hold a series of heap snapshots
together with additional information required to interpret those
snapshots. *)
type t
(** [create ~path] creates a series file at [path]. *)
val create : path:string -> t
(** [save_event] writes an event, which is an arbitrary string, into the
given series file. This may be used for identifying particular points
during program execution when analysing the profile.
The optional [time] parameter is as for [Snapshot.take].
*)
val save_event : ?time:float -> t -> event_name:string -> unit
(** [save_and_close series] writes information into [series] required for
interpeting the snapshots that [series] contains and then closes the
[series] file. This function must be called to produce a valid series
file.
The optional [time] parameter is as for [Snapshot.take].
*)
val save_and_close : ?time:float -> t -> unit
end
module Snapshot : sig
(** [take series] takes a snapshot of the profiling annotations on the values
in the minor and major heaps, together with GC stats, and write the
result to the [series] file. This function triggers a minor GC but does
not allocate any memory itself.
If the optional [time] is specified, it will be used instead of the
result of [Sys.time] as the timestamp of the snapshot. Such [time]s
should start from zero and be monotonically increasing. This parameter
is intended to be used so that snapshots can be correlated against wall
clock time (which is not supported in the standard library) rather than
elapsed CPU time.
*)
val take : ?time:float -> Series.t -> unit
end
(** Like [Series.save_event], but writes to the automatic snapshot file.
This function is a no-op if OCAML_SPACETIME_INTERVAL was not set. *)
val save_event_for_automatic_snapshots : event_name:string -> unit
|
