(** Encoding and decoding of allocation backtrace data for memory tracing.

    This module provides efficient serialization and deserialization of
    backtrace information associated with memory allocations. *)

module Writer : sig
  type t
  (** Encoder state for writing backtrace data. *)

  val create : unit -> t
  (** [create ()] initializes a new backtrace encoder. *)

  val max_length : int
  (** Maximum number of bytes written by [put_backtrace]. *)

  val put_backtrace :
    t ->
    Buf.Write.t ->
    alloc_id:int ->
    callstack:int array ->
    callstack_pos:int ->
    callstack_len:int ->
    log_new_location:(index:int -> unit) ->
    int (* number of encoded slots *)
  (** [put_backtrace encoder buffer ~alloc_id ~callstack ~callstack_pos
       ~callstack_len ~log_new_location] encodes a backtrace for an allocation
      into [buffer]. Returns the number of encoded callstack slots. The
      [log_new_location] callback is invoked for each newly encountered location
      index. *)

  val put_cache_verifier : t -> Buf.Write.t -> unit
  (** [put_cache_verifier encoder buffer] writes cache verification data to
      [buffer] for validation during deserialization. *)

  val put_dummy_verifier : Buf.Write.t -> unit
  (** [put_dummy_verifier buffer] writes a dummy verifier to [buffer] when cache
      verification is not needed. *)
end

module Reader : sig
  type t
  (** Decoder state for reading backtrace data. *)

  val create : unit -> t
  (** [create ()] initializes a new backtrace decoder. *)

  val get_backtrace :
    t -> Buf.Read.t -> nencoded:int -> common_pfx_len:int -> int array * int
  (** [get_backtrace decoder buffer ~nencoded ~common_pfx_len] decodes a
      backtrace from [buffer]. The [nencoded] parameter specifies the number of
      encoded slots, and [common_pfx_len] is the length of the common prefix
      with the previous backtrace. Returns the decoded callstack array and its
      length. *)

  val skip_backtrace :
    t -> Buf.Read.t -> nencoded:int -> common_pfx_len:int -> unit
  (** [skip_backtrace decoder buffer ~nencoded ~common_pfx_len] advances
      [buffer] past a backtrace without decoding it. *)

  type cache_verifier
  (** Verification token for backtrace cache consistency. *)

  val get_cache_verifier : Buf.Read.t -> cache_verifier
  (** [get_cache_verifier buffer] extracts a cache verifier from [buffer]. *)

  val check_cache_verifier : t -> cache_verifier -> bool
  (** [check_cache_verifier decoder verifier] validates the cache using the
      given verifier, returning [true] if valid. *)
end