Module Lwt_switch

Instructions: Use this module in your project

In the IDE (CLion, Visual Studio Code, Xcode, etc.) you use for your DkSDK project:

Add the following to your project's dependencies/CMakeLists.txt:

Copy

DkSDKProject_DeclareAvailable(lwt
    CONSTRAINT "= 5.6.1"
    FINDLIBS lwt lwt.unix)
DkSDKProject_MakeAvailable(lwt)

Add the Findlib::lwt library to any desired targets in src/*/CMakeLists.txt:

Copy

target_link_libraries(YourPackage_YourLibraryName
     # ... existing libraries, if any ...
     Findlib::lwt)

Click your IDE's Build button

Not using DkSDK?

FIRST, do one or all of the following:

Run:
Copy
```
opam install lwt.5.6.1
```

Edit your dune-project and add:

Copy

(package
  (name YourExistingPackage)
  (depends
  ; ... existing dependenices ...
  (lwt (>= 5.6.1))))

Then run:

Copy

dune build *.opam # if this fails, run: dune build

Edit your <package>.opam file and add:

Copy

depends: [
  # ... existing dependencies ...
  "lwt" {>= "5.6.1"}
]

Then run:

Copy

opam install . --deps-only

FINALLY, add the lwt library to any desired (library)and/or (executable) targets in your **/dune files:

Copy

(library
  (name YourLibrary)
  ; ... existing library options ...
  (libraries
    ; ... existing libraries ...
    lwt))

(executable
  (name YourExecutable)
  ; ... existing executable options ...
  (libraries
    ; ... existing libraries ...
    lwt))

Switch has two goals:

being able to free multiple resources at the same time,
offer a better alternative than always returning an id to free some resource.

For example, consider the following interface:

Copy

type id

val free : id -> unit Lwt.t

val f : unit -> id Lwt.t
val g : unit -> id Lwt.t
val h : unit -> id Lwt.t

Now you want to call f, g and h in parallel. You can simply do:

Copy

lwt idf = f () and idg = g () and idh = h () in
...

However, one may want to handle possible failures of f (), g () and h (), and disable all allocated resources if one of these three threads fails. This may be hard since you have to remember which one failed and which one returned correctly.

Now if we change the interface a little bit:

Copy

val f : ?switch : Lwt_switch.t -> unit -> id Lwt.t
val g : ?switch : Lwt_switch.t -> unit -> id Lwt.t
val h : ?switch : Lwt_switch.t -> unit -> id Lwt.t

the code becomes:

Copy

Lwt_switch.with_switch (fun switch ->
  lwt idf = f ~switch ()
  and idg = g ~switch ()
  and idh = h ~switch () in
  ...
)

type t

Type of switches.

valcreate : ``unit-> t

create () creates a new switch.

val with_switch : ``(t -> 'a Lwt.t)`` -> 'a Lwt.t

with_switch fn is fn switch, where switch is a fresh switch that is turned off when the callback thread finishes (whether it succeeds or fails).

since 2.6.0

valis_on :t -> bool

is_on switch returns true if the switch is currently on, and false otherwise.

valturn_off :t ->``unitLwt.t

turn_off switch turns off the switch. It calls all registered hooks, waits for all of them to terminate, then returns. If one of the hooks failed, it will fail with the exception raised by the hook. If the switch is already off, it does nothing.

exception Off

Exception raised when trying to add a hook to a switch that is already off.

valcheck :toption``-> unit

check switch does nothing if switch is None or contains an switch that is currently on, and raises Off otherwise.

valadd_hook :toption``->``(``unit->``unitLwt.t)`` -> unit

add_hook switch f registers f so it will be called when turn_off is invoked. It does nothing if switch is None. If switch contains an switch that is already off then Off is raised.

valadd_hook_or_exec :toption``->``(``unit->``unitLwt.t)`` ->``unitLwt.t

add_hook_or_exec switch f is the same as add_hook except that if the switch is already off, f is called immediately.

Module Lwt_switch

Contents

Not using DkSDK?

More from the DkSDK Book