= Lwt support

The {{{js_of_ocaml-lwt}}} package provides integration between Lwt and browser APIs.
It includes:

* {{{Lwt_js}}} — basic JavaScript bindings (sleep, yield)
* {{{Lwt_js_events}}} — DOM event handling with Lwt
* {{{Lwt_xmlHttpRequest}}} — XMLHttpRequest with Lwt
* {{{Lwt_jsonp}}} — JSONP requests

==@@id="events"@@ Events

The <<a_api subproject="js_of_ocaml-lwt"|module Js_of_ocaml_lwt.Lwt_js_events>> module
provides a concise way to handle DOM events using Lwt threads, as an alternative to
<<a_api subproject="js_of_ocaml" text="Dom_html.addEventListener"|val Js_of_ocaml.Dom_html.addEventListener>>.

This module defines functions you can call on a DOM element to create
an Lwt thread that will return when the event occurs.

Example:

<<code language="ocaml"|
Lwt.ignore_result (Lwt_js_events.click target ~>>= handler)
>>

The handler receives the JS event as parameter.

Each of these functions has a version (same name with an ending "s")
that loops when the handler terminates:

<<code language="ocaml"|
Lwt.ignore_result (Lwt_js_events.clicks target handler)
>>

==@@id="cancellation"@@ Cancellation

To remove an event handler, cancel the Lwt thread using {{{Lwt.cancel}}}.
You can also use {{{Lwt.pick}}}. For example, the following code waits
for a click on either {{{t1}}} or {{{t2}}}:

<<code language="ocaml"|
Lwt.pick [
  Lwt_js_events.click t1 ~>>= handler1;
  Lwt_js_events.click t2 ~>>= handler2
]
>>

**Warning**: If you use {{{Lwt.pick}}} and your handlers take time,
other event listeners will not be cancelled until the handler terminates.
It is better to return immediately after launching long-running handlers.

==@@id="api-reference"@@ API reference

See <<a_api subproject="js_of_ocaml-lwt"|module Js_of_ocaml_lwt.Lwt_js_events>>
for the full API.

== See also

* <<a_manual chapter="javascript-interop"|JavaScript interop>> — JavaScript binding fundamentals
* <<a_api subproject="js_of_ocaml-lwt"|index>> — Full Lwt support API
