lwt.mli (4248B)
1 (* Module [Lwt]: cooperative light-weight threads. *) 2 3 type 'a t 4 (* The type of threads returning a result of type ['a]. *) 5 6 val return : 'a -> 'a t 7 (* [return e] is a thread whose return value is the value of 8 the expression [e]. *) 9 10 val fail : exn -> 'a t 11 (* [fail e] is a thread that fails with the exception [e]. *) 12 13 val bind : 'a t -> ('a -> 'b t) -> 'b t 14 (* [bind t f] is a thread which first waits for the thread [t] 15 to terminate and then, if the thread succeeds, behaves as the 16 application of function [f] to the return value of [t]. If 17 the thread [t] fails, [bind t f] also fails, with the same 18 exception. 19 20 The expression [bind t (fun x -> t')] can intuitively be read 21 as [let x = t in t']. 22 23 Note that [bind] is also often used just for synchronization 24 purpose: [t'] will not execute before [t] is terminated. 25 26 The result of a thread can be bound several time. *) 27 28 val (>>=) : 'a t -> ('a -> 'b t) -> 'b t 29 (* [t >>= f] is an alternative notation for [bind t f]. *) 30 31 val catch : (unit -> 'a t) -> (exn -> 'a t) -> 'a t 32 (* [catch t f] is a thread that behaves as the thread [t ()] if 33 this thread succeeds. If the thread [t ()] fails with some 34 exception, [catch t f] behaves as the application of [f] to 35 this exception. *) 36 37 val try_bind : (unit -> 'a t) -> ('a -> 'b t) -> (exn -> 'b t) -> 'b t 38 (* [try_bind t f g] behaves as [bind (t ()) f] if [t] does not fail. 39 Otherwise, it behaves as the application of [g] to the 40 exception associated to [t ()]. *) 41 42 val choose : 'a t list -> 'a t 43 (* [choose l] behaves as the first thread in [l] to terminate. 44 If several threads are already terminated, one is chosen 45 at random. *) 46 47 val ignore_result : 'a t -> unit 48 (* [ignore_result t] start the thread [t] and ignores its result 49 value if the thread terminates successfully. However, if the 50 thread [t] fails, the exception is raised instead of being 51 ignored. 52 You should use this function if you want to start a thread 53 and don't care what its return value is, nor when it 54 terminates (for instance, because it is looping). 55 Note that if the thread [t] yields and later fails, the 56 exception will not be raised at this point in the program. *) 57 58 val wait : unit -> 'a t 59 (* [wait ()] is a thread which sleeps forever (unless it is 60 resumed by one of the functions [wakeup], [wakeup_exn] below). 61 This thread does not block the execution of the remainder of 62 the program (except of course, if another thread tries to 63 wait for its termination). *) 64 65 (* Execution order 66 A thread executes as much as possible. Switching to another 67 thread is always explicit. 68 69 Exception handling 70 - You must use "fail e" instead of "raise e" if you want the 71 exception to be wrapped into the thread. 72 - The construction [try t with ...] will not caught the 73 exception associated to the thread [t] if this thread fails. 74 You should use [catch] instead. *) 75 76 (****) 77 78 (* The functions below are probably not useful for the casual user. 79 They provide the basic primitives on which can be built multi- 80 threaded libraries such as Lwt_unix. *) 81 82 val poll : 'a t -> 'a option 83 (* [poll e] returns [Some v] if the thread [e] is terminated and 84 returned the value [v]. If the thread failed with some 85 exception, this exception is raised. If the thread is still 86 running, [poll e] returns [None] without blocking. *) 87 88 val wakeup : 'a t -> 'a -> unit 89 (* [wakeup t e] makes the sleeping thread [t] terminate and 90 return the value of the expression [e]. *) 91 val wakeup_exn : 'a t -> exn -> unit 92 (* [wakeup_exn t e] makes the sleeping thread [t] fail with the 93 exception [e]. *) 94 95 val apply : ('a -> 'b t) -> 'a -> 'b t 96 (* [apply f e] apply the function [f] to the expression [e]. If 97 an exception is raised during this application, it is caught 98 and the resulting thread fails with this exception. *) 99 (* Q: Could be called 'glue' or 'trap' or something? *)