Update Lwt tutorial examples to match new tutorial

[talex5]

In particular:

• Change C.log to log_s. log is the emergency non-blocking version
  that discards data if the buffer is full. We should not encourage its
  use in a tutorial. Also, it doesn't demonstrate using Lwt.
• Use >>= rather than >|= because the tutorial didn't introduce it
  yet.
• Don't use _ to ignore exceptions in timeout example.
• Moved some functions out of start for clarity.
• Remove mvar and stream examples, as they're no longer in the tutorial.

See: mirage/mirage-www#458

[talex5]

(I feel a bit bad about deleting the mvar and stream examples. @mor1 : do you think we should keep these?)

[mor1]

Guess it depends whether they're useful :)
@djs55 @avsm @samoht Would it be considered good practice with Mirage things to use mvars and streams? (Presumably yes to the first, but ISTR some commentary that streams not so good.)
If so, then I'd leave them in and file an issue against the tutorial to add some reference to them.

[samoht]

I try to stay away from mvars and streams (and I usually don't use them -- apart stream in some special cases). So I'm happy with that change.

[djs55]

I don't use mvars at all and hardly ever use streams (iirc they're hard to use correctly). The main thing I use is "lwt.task" which is like an immutable mvar (aka an Ivar or deferred or thread)

[hannesm]

I use streams over here in IKEv2... and think this is a viable use case (merging the different streams, data from kernel, data via udp, timer tick)... mvar are also useful synchronisation primitives (I do use them in jackline, but am not yet satisfied with their usage over there)... but I guess it doesn't need to be in the lwt tutorial (though some people told me that mirage-skeleton is too basic, examples like a multi-client echo server (including broadcasting) would be useful)

[mor1]

Ok so perhaps the things to do are: leave them in skeleton for now (assuming they build) and maybe file an issue against mirage-www (or comment on mirage/mirage-www#432) suggesting that some "advanced" -- perhaps network service specific? -- extra tutorial material showing how they're used might be useful? I'm loathe to just get rid of working examples in a sample code repo even if they're not ref'd on the website.

[hannesm]

..or just remove them and at some point add some with a suitable story and examples?

[mor1]

Yes that's the other obvious option; but as I said, I generally prefer to keep working examples around as they might be useful to someone and I don't think having them in there without reference is particularly confusing. Ofc, if there's a good source of more generic Lwt examples showing how to use some of these features, then there's no need for them to remain here particularly. But if there isn't another alternative, why reduce the number of viable code samples out there?

[talex5]

I don't use mvars much either. Could you explain where they're useful? The main place I've seen them used is in the tcp stack, but several people have suggested the code would be clearer if we removed them.

I guess they're more useful in a multi-core preemptive system where you want a consumer and producer to run in parallel on different cores, but in Lwt that doesn't apply: in many cases (as in the example code) you might as well have the producer call the consumer directly.

e.g. the example does

let map f m_in =
  let m_out = Lwt_mvar.create_empty () in
  let rec aux () =
    Lwt_mvar.(
      take m_in   >>=
      f           >>= fun v ->
      put m_out v >>= fun () ->
      aux ()
    )
  in
  let _t = aux () in
  m_out

let start c =
  let m_input = Lwt_mvar.create_empty () in
  let m_output = m_input |> map wait_strlen |> map cap_str in

  let rec read () =
    read_line ()           >>= fun s ->
    Lwt_mvar.put m_input s >>=
    read
  in
  let rec write () =
    Lwt_mvar.take m_output >>= fun r ->
    C.log c r;
    write ()
  in
  (read ()) <&> (write ())

But if you dropped the mvars, you could replace the whole thing with just:

  let start c =
    let rec loop () =
      read_line () >>= wait_strlen >>= cap_str >|= C.log c >>= fun () ->
      loop () in
    loop ()

[mor1]

@talex5 I don't know why mvars are useful, and nor do I claim they're useful above. I think that working code samples that add to existing documentation are useful, particularly if they explain features that we do actually use, however misguidedly. There doesn't seem to me to be a requirement that only things in our tutorial are in this part of the repo.

If mvars should be removed from the TCP stack then is there an issue to that effect?

Similarly, if actually Lwt.tasks are the preferred thing to use (per @djs55 comment), then it would be nice to add an example of those here and to the tutorial (or to point to examples of such in the existing Lwt tutorial material).

[hannesm]

this should be merged since the website part is online now. objections?

[mor1]

As noted above -- I'd probably prefer to see the mvar and stream examples not be removed in this PR.

But either way, it should be merged soon, yes.

[aantron]

ISTR some commentary that streams not so good

I don't use mvars at all and hardly ever use streams (iirc they're hard to use correctly)

This is a bit of a hijack, but if any of the participants here has interest in/complaints about Lwt's streams, I would really appreciate if you can comment here:

Lwt_stream sucks (?) (ocsigen/lwt#250).

Perhaps the situation can be improved in some way.

[dbuenzli]

I vaguely remember @pqwy making me a funny account of Lwt_streams internals when he was obsessed about streaming abstractions at some point.

[dbuenzli]

I think that working code samples that add to existing documentation are useful, particularly if they explain features that we do actually use, however misguidedly.

Well no, remove things that are unused, they are only distractions to newcomers. That's the kind of way you end up with useless crap on the mirageos website...

[talex5]

Most people seem in favour of removing these, so will merge this soon. I don't see any point in providing examples we don't want anyone to read.

(and @yomimono has archived the other page @dbuenzli mentioned - thanks!)