Module Conv.Exn_converter

module Exn_converter: sig .. end

type t 

Type of handles for exception S-expression converters

val set_max_exn_tags : 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.

val get_max_exn_tags : 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.

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.