{"id":28184197,"url":"https://github.com/robur-coop/miou","last_synced_at":"2026-06-08T21:00:34.915Z","repository":{"id":179681829,"uuid":"663965575","full_name":"robur-coop/miou","owner":"robur-coop","description":"A simple scheduler for OCaml 5","archived":false,"fork":false,"pushed_at":"2026-06-08T09:15:10.000Z","size":4220,"stargazers_count":139,"open_issues_count":11,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-08T11:13:50.619Z","etag":null,"topics":["effects","ocaml","parallelism","scheduler"],"latest_commit_sha":null,"homepage":"https://docs.osau.re/local/miou/index.html","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robur-coop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-08T14:58:11.000Z","updated_at":"2026-06-07T20:48:36.000Z","dependencies_parsed_at":"2023-10-03T16:40:03.134Z","dependency_job_id":"59b5c717-e732-4476-863e-16aab1d9d0d8","html_url":"https://github.com/robur-coop/miou","commit_stats":null,"previous_names":["roburio/miou","robur-coop/miou"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/robur-coop/miou","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiou","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiou/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiou/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiou/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robur-coop","download_url":"https://codeload.github.com/robur-coop/miou/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Fmiou/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34080026,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["effects","ocaml","parallelism","scheduler"],"created_at":"2025-05-16T05:12:24.258Z","updated_at":"2026-06-08T21:00:34.908Z","avatar_url":"https://github.com/robur-coop.png","language":"OCaml","funding_links":[],"categories":["Concurrency","\u003ca name=\"OCaml\"\u003e\u003c/a\u003eOCaml"],"sub_categories":[],"readme":"# Miou, a simple scheduler for OCaml 5\n\n```ocaml\nlet () = Miou.run @@ fun () -\u003e\n  print_endline \"Hello World!\"\n```\n\nMiou is a library designed to facilitate the development of applications\nrequiring concurrent and/or parallel tasks. This library has been developed with\nthe aim of offering a fairly simple and straightforward design. It's a pretty\nsmall library with few dependencies that frames the behaviour of applications\nusing precise and conservative rules to guide users in their development.\n\nThe API documentation is available [here][documentation]. It describes (with\nexamples) Miou's behaviour. The official repository is available\n[here][repository]. The project is being maintained by the [robur.coop][robur]\ncooperative.\n\nMiou is focusing on 2 objectives:\n- to provide a best-practice approach to the development of OCaml applications\n  requiring concurrency and/or parallelism\n- composability that can satisfy the most limited contexts, such as unikernels\n\nMiou meets these objectives by:\n- conservative and stable rules for the library's behaviour\n- an API that delegates suspension management to the user\n\nA [book][book] is available which explains how to make applications with Miou in\ndetails. It introduces the reader to effects, implements a small scheduler and a\nsmall echo server as an example. You an also read a simple tutorial from our\ndocumentation explaining how to implement this echo server with [here][echo].\n\n### Rules\n\nMiou complies with several rules that the user must respect. These rules (which\ncan be restrictive) help to guide the user towards good practice and avoid\n*anti-patterns*. This notion of rules and anti-patterns is arbitrary\n\u003csup\u003e[1](#fn1)\u003c/sup\u003e - it can therefore be criticised and/or disengage the\ndeveloper from using Miou. These rules come from our experience of system\nprogramming in OCaml, where the development of our software today confirms\ncertain anti-patterns that we would not want to reproduce today (in view of the\ntechnical debt that these bring).\n\n#### Creating and waiting for a task\n\nThere are 2 ways of creating a task:\n- it can run concurrently with other tasks and execute on the domain in which it\n  was created (see `Miou.async`)\n- it can run in parallel with other tasks and be executed on **another** domain\n  (see `Miou.call`)\n\nThe first rule to follow is that the user must wait for all the tasks he/she has\ncreated. If they don't, Miou raises an exception: `Still_has_children`:\n```ocaml\nlet () = Miou.run @@ fun () -\u003e\n  ignore (Miou.async @@ fun () -\u003e 42)\nException: Miou.Still_has_children\n```\n\nThe user must therefore take care to use `Miou.await` for all the tasks\n(concurrent and parallel) that he/she has created:\n```ocaml\nlet () = Miou.run @@ fun () -\u003e\n  let p0 = Miou.async @@ fun () -\u003e 42 in\n  Miou.await_exn p0\n```\n\n#### Relationships between tasks\n\nA task can only be awaited by the person who created it.\n```ocaml\nlet () = Miou.run @@ fun () -\u003e\n  let p0 = Miou.async @@ fun () -\u003e 42 in\n  let p1 = Miou.async @@ fun () -\u003e Miou.await_exn p0 in\n  Miou.await_exn p1\nException: Miou.Not_a_child\n```\n\nThis rule dictates that passing values from one task to another requires\n(pragmatically) that a resource be allocated accordingly to represent such a\ntransmission. It also reaffirms that such a passage of values must surely be\nprotected by synchronisation mechanisms between the said tasks (with\n`Miou.Mutex` or `Miou.Condition`).\n\nThe only valid relationship (and transmission of values) between 2 tasks offered\nby Miou is that between a child and its parent.\n\n#### Abnormal termination\n\nIf a task fails (with an exception), all its sub-tasks also end.\n\n```ocaml\nlet prgm () = Miou_unix.run @@ fun () -\u003e\n  let p = Miou.async @@ fun () -\u003e\n    let q = Miou.async @@ fun () -\u003e Miou_unix.sleep 1. in\n    raise (Failure \"p\") in\n  Miou.await p\n\nlet () =\n  let t0 = Unix.gettimeofday () in\n  let _  = prgm () in\n  let t1 = Unix.gettimeofday () in\n  assert (t1 -. t0 \u003c 1.)\n```\n\nThis code shows that if `p` fails, we also stop `q` (which should wait at least\n1 second). This shows that our `prgm` didn't actually last a second. Abnormal\ntermination will always attempt to complete all sub-tasks so that there are no\n*zombie* tasks.\n\n#### Wait or cancel\n\nIt was explained above that all children must be waited on by the task that\ncreated them. However, the user can also `Miou.cancel` a task - of course, this\nproduces an abnormal termination of the task which automatically results in the\ntermination of all its children.\n\n```ocaml\nlet () = Miou.run @@ fun () -\u003e\n  Miou.cancel (Miou.async @@ fun () -\u003e 42)\n```\n\nThis code shows that if it is not possible to `ignore` the result of a task, it\nis still possible to `cancel` it.\n\n#### Randomised tasks\n\nTasks are taken randomly. That is to say that this code could return 1 as 2.\n```ocaml\nlet prgm () =\n  Miou.run @@ fun () -\u003e\n  let a = Miou.async (Fun.const 1) in\n  let b = Miou.async (Fun.const 2) in\n  Miou.await_first [ a; b ]\n\nlet rec until_its n =\n  match prgm () with\n  | Ok n' when n = n' -\u003e ()\n  | _ -\u003e until_its n\n\nlet () =\n  until_its 1;\n  until_its 2\n```\n\nThis code shows that it is possible for our program to return 1 or 2. The reason\nwhy we decided to randomly select the promises allows:\n1) extend the coverage of your code\n2) be less sensitive to predictions that could help an attacker\n\n\u003chr\u003e\n\n\u003ctag id=\"fn1\"\u003e**1**\u003c/tag\u003e: This arbitrary consideration proves that the answer\nto the development of concurrent and/or parallel applications cannot be\nabsolute, and is based on individual affects and principles. Once again, we are\nnot suggesting that Miou is the ultimate solution to these problems, and we will\nnot commit ourselves to treating Miou as a viable solution from all points of\nview.\n\nWe just believe that it corresponds to our problems and our points of view. It\nis then up to the user to (dis)consider all this - which, as it stands, is much\nmore than a strictly technical description.\n\n### Suspension and API\n\nMiou finally proposes that the management of the suspension be delegated to the\nuser. Indeed, task management focuses mainly on suspension management: that is,\na task that can *block* the process.\n\nIt turns out that suspend mainly\u003csup\u003e[2](#fn2)\u003c/sup\u003e only affects the use of\nresources offered by the system (sockets, files, time, etc.). Our experience in\nsystem programming and in the development of unikernels teaches us that this\nmanagement of system resources, although intrinsic to task management, is:\n- complex because of the subtleties that may exist between each system (Linux,\n  \\*BSD, Mac, Windows, unikernels)\n- specific to the case of the suspension of a task while waiting for a signal\n  from the system\n\nAs such and in our objective of composability with exotic systems, we have\ndecided to offer the user two libraries:\n- `miou`, which is the core of our project\n- `miou.unix`, which is an extension of our core with I/O\n\nThe second takes advantage of the API of the first regarding suspension. There\nis a [tutorial][sleepers] explaining this API step by step and how to use it so\nthat you can manage everything related to suspension (and, by extension, your\nsystem resources through the API it can offer).\n\n\u003chr\u003e\n\n\u003ctag id=\"fn2\"\u003e**2**\u003c/tag\u003e: It is noted that the suspension does not concern only\nI/O and the resources of a system. Mutexes, conditions or semaphores can also\nsuspend the execution of a program. Our documentation and tutorials explain\nthose cases that we consider *marginal* in the interest of internalizing\nsuspension mechanism rather than exporting it to the user (but which are equally\nimportant in the design of an application).\n\n## Genesis\n\nThe development of Miou began following discussions with a number of actors,\nwhere we noted certain differences of opinion. We were not satisfied with the\ndifferent signals we received on the problem of scheduling in the OCaml\necosystem, despite repeated efforts to reconcile these differences. Miou does\nnot present itself as the absolute solution to the scheduling problem. It is\nsimply the reemergence of these opinions in another environment which has\nunfortunately not been offered by the actors who had the opportunity to do so.\n\nWe would like to make it clear that we do not want to monopolise and/or compete\nwith anyone. We would also like to inform future users that Miou regards our\nobjectives and our vision - which you may not agree with. So, if Miou satisfies\nyou in its approach (and that of its maintainers), and its objectives (and those\nof its users), welcome!\n\n## Memento\n\nIf readers are interested in the OCaml ecosystem and the role Miou could play\nin it, we would also like to refer them to this [discuss post][discuss], which\nsummarises our objectives and how we would like to become part of the OCaml\ncommunity.\n\nWe would also like to affirm that our position is always one of collaboration\nwith others. We do not impose the use of Miou (as we do little to promote it),\nbut we would not want anyone to impose their solution on us without prior\ndiscussion and a search for compromise (as we systematically do when\nparticipating in projects that do not belong to us).\n\nSince the beginning of OCaml 5 and the appearance of schedulers, we have seen\nvery little collaborative approach to finding a solution and have mainly\nnoticed behaviour that is at best dogmatic and sometimes problematic (according\nto [the OCaml CoC][coc]). As such, although we remain open, we no longer\nnecessarily have the energy to promote and build bridges with other schedulers.\nHowever, we would be delighted to continue improving the experience of our\nusers and the OCaml community in general.\n\n[repository]: https://github.com/robur-coop/miou\n[github]: https://github.com/robur-coop/miou\n[documentation]: https://docs.osau.re/local/miou/\n[sleepers]: https://docs.osau.re/local/miou/sleepers.html\n[echo]: https://docs.osau.re/local/miou/echo.html\n[robur]: https://robur.coop/\n[book]: https://robur-coop.github.io/miou\n[discuss]: https://discuss.ocaml.org/t/on-concurrency-models/15899/13?u=dinosaure\n[coc]: https://ocaml.org/policies/code-of-conduct\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobur-coop%2Fmiou","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobur-coop%2Fmiou","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobur-coop%2Fmiou/lists"}