Lazy - Deferred computations.

       Module Lazy
        : sigend

       Deferred computations.

       type'at = 'aCamlinternalLazy.t

       A  value of type 'aLazy.t is a deferred computation, called a suspension, that has a result of type 'a .
       The special expression syntax lazy(expr) makes a  suspension  of  the  computation  of  expr  ,  without
       computing  expr  itself  yet.  "Forcing"  the  suspension  will  then compute expr and return its result.
       Matching a suspension with  the  special  pattern  syntax  lazy(pattern)  also  computes  the  underlying
       expression and tries to bind it to pattern :

             letlazy_option_mapfx=matchxwith|lazy(Somex)->Some(Lazy.forcefx)|_->None

       Note:  If  lazy  patterns  appear in multiple cases in a pattern-matching, lazy expressions may be forced
       even outside of the case ultimately  selected  by  the  pattern  matching.  In  the  example  above,  the
       suspension x is always computed.

       Note:  lazy_t is the built-in type constructor used by the compiler for the lazy keyword.  You should not
       use it directly.  Always use Lazy.t instead.

       Note: Lazy.force is not concurrency-safe. If you use this module  with  multiple  fibers,  systhreads  or
       domains,  then  you  will  need  to  add some locks. The module however ensures memory-safety, and hence,
       concurrently accessing this module will not lead to a crash but the behaviour is unspecified.

       Note: if the program is compiled with the -rectypes option, ill-founded recursive definitions of the form
       letrecx=lazyx or letrecx=lazy(lazy(...(lazyx))) are accepted by the type-checker and lead, when
       forced, to ill-formed values that trigger infinite loops in the garbage collector and other parts of  the
       run-time  system.   Without  the -rectypes option, such ill-founded recursive definitions are rejected by
       the type-checker.

       exceptionUndefined

       Raised when forcing a suspension concurrently from multiple fibers, systhreads or domains,  or  when  the
       suspension tries to force itself recursively.

       valforce : 'at->'aforcex  forces  the  suspension  x  and  returns its result. If x has already been forced, Lazy.forcex
       returns the same value again without recomputing it.  If it raised an exception, the  same  exception  is
       raised again.

       RaisesUndefined (see Lazy.Undefined ).

   Iteratorsvalmap : ('a->'b)->'at->'btmapfx returns a suspension that, when forced, forces x and applies f to its value.

       It is equivalent to lazy(f(Lazy.forcex)) .

       Since 4.13

   Reasoningonalready-forcedsuspensionsvalis_val : 'at->boolis_valx returns true if x has already been forced and did not raise an exception.

       Since 4.00

       valfrom_val : 'a->'atfrom_valv  evaluates  v  first  (as any function would) and returns an already-forced suspension of its
       result.  It is the same as letx=vinlazyx , but uses dynamic tests to optimize  suspension  creation
       in some cases.

       Since 4.00

       valmap_val : ('a->'b)->'at->'btmap_valfx applies f directly if x is already forced, otherwise it behaves as mapfx .

       When  x is already forced, this behavior saves the construction of a suspension, but on the other hand it
       performs more work eagerly that may not be useful if you never force the function result.

       If f raises an exception, it will be raised immediately when is_valx , or raised only when  forcing  the
       thunk otherwise.

       If map_valfx does not raise an exception, then is_val(map_valfx) is equal to is_valx .

       Since 4.13

   Advanced
       The  following definitions are for advanced uses only; they require familiarity with the lazy compilation
       scheme to be used appropriately.

       valfrom_fun : (unit->'a)->'atfrom_funf is the same as lazy(f()) but slightly more efficient.

       It should only be used if the function f is already defined.  In particular it is always  less  efficient
       to write from_fun(fun()->expr) than lazyexpr .

       Since 4.00

       valforce_val : 'at->'aforce_valx  forces  the suspension x and returns its result.  If x has already been forced, force_valx
       returns the same value again without recomputing it.

       If the computation of x raises an exception, it is  unspecified  whether  force_valx  raises  the  same
       exception or Lazy.Undefined .

       RaisesUndefined if the forcing of x tries to force x itself recursively.

       RaisesUndefined (see Lazy.Undefined ).

OCamldoc                                           2025-06-12                                           Lazy(3o)

       Module   Lazy

       Lazy - Deferred computations.