module Exn_converter:sig
..end
type
t
int -> unit
: set_max_exn_tags n
sets the maximum number of converters for exceptions
with the same template to n
. If already existing handlers exceed
this number, they will remain at their current number until this number
is reduced due to garbage collection. New handlers will not be added
until n
will not be exceeded.unit -> int
: set_max_exn_tags ()
return the maximum number of converters for
exceptions with the same template.val add_auto : ?finalise:bool -> exn -> (exn -> Sexp.t) -> unit
add_auto ?finalise templ sexp_of_exn
registers exception S-expression
converter sexp_of_exn
for exceptions having same constructor as
template templ
, unless the number of stored handlers for the given
template exceeds get_max_exn_tags ()
, in which case the handler will
never be called. When sexp_of_exn
is called, the passed exception
is guaranteed to match the template.
NOTE: if the exception belongs to a transient module, e.g. local modules
(including functor instantiations), first-class modules, etc., a manually
written sexp_of_exn
must use Obj.magic
internally to avoid matching
or creating the exception, otherwise the handler can never be reclaimed
once the exception ceases to exist. If finalise
is true
, then
the exception will be automatically registered for removal with the GC
(default). Finalisation will not work with exceptions that have been
allocated outside the heap, which is the case for some standard ones
e.g. Sys_error
.
NOTE: Use with great caution, this function is primarily intended for
automated use! If unsure, use add_slow
instead.
finalise
: default = true
val add_slow : (exn -> Sexp.t option) -> t
add_slow sexp_of_exn
registers exception S-expression converter
sexp_of_exn
and returns a handle. Exception converters registered this
way are much slower than with add
, but this function does not require
an exception template. NOTE: if you call this function explicitly,
or the "sexp"-macro for exceptions from within local modules, you will
eventually have to unregister it manually with del
, otherwise there
is a space leak!val del_slow : t -> unit
del_slow handle
unregisters exception S-expression converter with
handle handle
. In multi-threaded contexts it is not guaranteed
that the unregistered converter will not be called after this function
returns.