<commit_before>(* OCaml promise library
 * http://www.ocsigen.org/lwt
 * Copyright (C) 2005-2008 <NAME>
 * Laboratoire PPS - CNRS Université Paris Diderot
 *               2009-2012 <NAME>
 *               2017      <NAME>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, with linking exceptions;
 * either version 2.1 of the License, or (at your option) any later
 * version. See COPYING file for details.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
 * 02111-1307, USA.
 *)



(** Asynchronous programming with promises.

    A {b promise} is a placeholder for a single value which might take a long
    time to compute. Speaking roughly, a promise is a [ref] that can be filled
    in later. To make that precise, here is how promises differ from [ref]s:

    - A promise might not have a value yet. A promise in this state is called a
      {e pending} promise.
    - Writing a value into a promise is called {e resolving} it. A promise with
      a value is called a {e resolved} promise.
    - Each promise can be resolved only once. After a promise has a value, the
      promise is immutable.
    - It's possible to attach {b callbacks} to a promise. They will run when the
      promise has a value, i.e. is resolved. If the promise is already resolved
      when a callback is attached, the callback is run (almost) right away. If
      the promise is pending, the callback is put into a list and waits.

    So, promises are optional, write-once references, and when they don't yet
    have a value, they store a list of callbacks that are waiting for the value.

    The waiting callbacks make promises a natural data type for asynchronous
    programming. For example, you can ask Lwt to [read] a file. Lwt immediately
    returns you only a {e promise} for the data.

    You can neglect this promise for a while. You can do some other computation,
    request more I/O, etc. At some point, you might decide to attach a callback
    to the [read] promise, maybe several callbacks.

    In the meantime, the [read] operation is running in the background. Once it
    finishes, Lwt {e resolves} the [read] promise by putting the data into it.
    Lwt then runs the callbacks you attached.

    One of those might take the data, and ask Lwt to [write] it to STDOUT. Lwt
    gives you a promise for that, too, and the process repeats.

    Lwt has a small amount of syntactic sugar to make this look as natural as
    possible:

{[
let () =
  Lwt_main.run begin
    let%lwt data = Lwt_io.(read_line stdin) in
    let%lwt () = Lwt_io.printl data in
    Lwt.return ()
  end

(* ocamlfind opt -linkpkg -package lwt.ppx,lwt.unix echo.ml && ./a.out *)
]}

    This is all explained in the next sections:

    - {{: #3_Quickstart} Quick start} links these concepts to actual functions
      in Lwt – the most fundamental ones.
    - {{: #3_Tutorial} Tutorial} shows how to write examples like the above, and
      how concurrency happens.
    - {{: #3_Executionmodel} Execution model} clarifies control flow when using
      Lwt.
    - {{: #3_GuidetotherestofLwt} Guide to the rest of Lwt} shows how
      {e everything} else in Lwt fits into this framework.

    After that is the {{: 2_Fundamentals} reference proper}, which goes into
    {e painful} levels of detail on every single type and value in this module,
    [Lwt]. Please be safe, and read only what you need from it :)

    Happy asynchronous programming!



    {3 Quick start}

    {e All} of Lwt is variations on:

    - {b Promises} of type ['a ]{!Lwt.t} are placeholders for values of type
      ['a].
    - {!Lwt.bind} attaches {b callbacks} to promises. When a promise gets a
      value, its callbacks are called.
    - Separate {b resolvers} of type ['a ]{!Lwt.u} are used to write values into
      promises, through {!Lwt.wakeup_later}.
    - Promises and resolvers are created in pairs using {!Lwt.task}. Lwt I/O
      functions call {!Lwt.task} internally, but return only the promise.
    - {!Lwt_main.run} is used to wait on one “top-level” promise. When that
      promise gets a value, the program terminates.



    {3 Tutorial}<commit_msg>Docs: fix section reference<commit_after>(* OCaml promise library
 * http://www.ocsigen.org/lwt
 * Copyright (C) 2005-2008 <NAME>
 * Laboratoire PPS - CNRS Université Paris Diderot
 *               2009-2012 <NAME>
 *               2017      <NAME>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, with linking exceptions;
 * either version 2.1 of the License, or (at your option) any later
 * version. See COPYING file for details.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
 * 02111-1307, USA.
 *)



(** Asynchronous programming with promises.

    A {b promise} is a placeholder for a single value which might take a long
    time to compute. Speaking roughly, a promise is a [ref] that can be filled
    in later. To make that precise, here is how promises differ from [ref]s:

    - A promise might not have a value yet. A promise in this state is called a
      {e pending} promise.
    - Writing a value into a promise is called {e resolving} it. A promise with
      a value is called a {e resolved} promise.
    - Each promise can be resolved only once. After a promise has a value, the
      promise is immutable.
    - It's possible to attach {b callbacks} to a promise. They will run when the
      promise has a value, i.e. is resolved. If the promise is already resolved
      when a callback is attached, the callback is run (almost) right away. If
      the promise is pending, the callback is put into a list and waits.

    So, promises are optional, write-once references, and when they don't yet
    have a value, they store a list of callbacks that are waiting for the value.

    The waiting callbacks make promises a natural data type for asynchronous
    programming. For example, you can ask Lwt to [read] a file. Lwt immediately
    returns you only a {e promise} for the data.

    You can neglect this promise for a while. You can do some other computation,
    request more I/O, etc. At some point, you might decide to attach a callback
    to the [read] promise, maybe several callbacks.

    In the meantime, the [read] operation is running in the background. Once it
    finishes, Lwt {e resolves} the [read] promise by putting the data into it.
    Lwt then runs the callbacks you attached.

    One of those might take the data, and ask Lwt to [write] it to STDOUT. Lwt
    gives you a promise for that, too, and the process repeats.

    Lwt has a small amount of syntactic sugar to make this look as natural as
    possible:

{[
let () =
  Lwt_main.run begin
    let%lwt data = Lwt_io.(read_line stdin) in
    let%lwt () = Lwt_io.printl data in
    Lwt.return ()
  end

(* ocamlfind opt -linkpkg -package lwt.ppx,lwt.unix echo.ml && ./a.out *)
]}

    This is all explained in the next sections:

    - {{: #3_Quickstart} Quick start} links these concepts to actual functions
      in Lwt – the most fundamental ones.
    - {{: #3_Tutorial} Tutorial} shows how to write examples like the above, and
      how concurrency happens.
    - {{: #3_Executionmodel} Execution model} clarifies control flow when using
      Lwt.
    - {{: #3_GuidetotherestofLwt} Guide to the rest of Lwt} shows how
      {e everything} else in Lwt fits into this framework.

    After that is the {{: #2_Fundamentals} reference proper}, which goes into
    {e painful} levels of detail on every single type and value in this module,
    [Lwt]. Please be safe, and read only what you need from it :)

    Happy asynchronous programming!



    {3 Quick start}

    {e All} of Lwt is variations on:

    - {b Promises} of type ['a ]{!Lwt.t} are placeholders for values of type
      ['a].
    - {!Lwt.bind} attaches {b callbacks} to promises. When a promise gets a
      value, its callbacks are called.
    - Separate {b resolvers} of type ['a ]{!Lwt.u} are used to write values into
      promises, through {!Lwt.wakeup_later}.
    - Promises and resolvers are created in pairs using {!Lwt.task}. Lwt I/O
      functions call {!Lwt.task} internally, but return only the promise.
    - {!Lwt_main.run} is used to wait on one “top-level” promise. When that
      promise gets a value, the program terminates.



    {3 Tutorial}
{'fraction_non_alphanumeric': 0.06850923060505816, 'fraction_numerical': 0.009177248959556078, 'mean_word_length': 2.9611158072696533, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6296377', 'n_tokens_mistral': 2718, 'n_tokens_neox': 2577, 'n_words': 1382}