gazagnaire.org
upstream: https://github.com/janestreet/memtrace
1(** Encoding and decoding of allocation backtrace data for memory tracing.
2
3 This module provides efficient serialization and deserialization of
4 backtrace information associated with memory allocations. *)
5
6module Writer : sig
7 type t
8 (** Encoder state for writing backtrace data. *)
9
10 val create : unit -> t
11 (** [create ()] initializes a new backtrace encoder. *)
12
13 val max_length : int
14 (** Maximum number of bytes written by [put_backtrace]. *)
15
16 val put_backtrace :
17 t ->
18 Buf.Write.t ->
19 alloc_id:int ->
20 callstack:int array ->
21 callstack_pos:int ->
22 callstack_len:int ->
23 log_new_location:(index:int -> unit) ->
24 int (* number of encoded slots *)
25 (** [put_backtrace encoder buffer ~alloc_id ~callstack ~callstack_pos
26 ~callstack_len ~log_new_location] encodes a backtrace for an allocation
27 into [buffer]. Returns the number of encoded callstack slots. The
28 [log_new_location] callback is invoked for each newly encountered location
29 index. *)
30
31 val put_cache_verifier : t -> Buf.Write.t -> unit
32 (** [put_cache_verifier encoder buffer] writes cache verification data to
33 [buffer] for validation during deserialization. *)
34
35 val put_dummy_verifier : Buf.Write.t -> unit
36 (** [put_dummy_verifier buffer] writes a dummy verifier to [buffer] when cache
37 verification is not needed. *)
38end
39
40module Reader : sig
41 type t
42 (** Decoder state for reading backtrace data. *)
43
44 val create : unit -> t
45 (** [create ()] initializes a new backtrace decoder. *)
46
47 val get_backtrace :
48 t -> Buf.Read.t -> nencoded:int -> common_pfx_len:int -> int array * int
49 (** [get_backtrace decoder buffer ~nencoded ~common_pfx_len] decodes a
50 backtrace from [buffer]. The [nencoded] parameter specifies the number of
51 encoded slots, and [common_pfx_len] is the length of the common prefix
52 with the previous backtrace. Returns the decoded callstack array and its
53 length. *)
54
55 val skip_backtrace :
56 t -> Buf.Read.t -> nencoded:int -> common_pfx_len:int -> unit
57 (** [skip_backtrace decoder buffer ~nencoded ~common_pfx_len] advances
58 [buffer] past a backtrace without decoding it. *)
59
60 type cache_verifier
61 (** Verification token for backtrace cache consistency. *)
62
63 val get_cache_verifier : Buf.Read.t -> cache_verifier
64 (** [get_cache_verifier buffer] extracts a cache verifier from [buffer]. *)
65
66 val check_cache_verifier : t -> cache_verifier -> bool
67 (** [check_cache_verifier decoder verifier] validates the cache using the
68 given verifier, returning [true] if valid. *)
69end