From 9edb9c842d847189b53239182e5cec1de5a2e688 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Wed, 15 Jan 2025 16:23:25 +0000 Subject: [PATCH] Minor documentation improvements - Remove reference to Meio until it's actually working with stable versions of Eio. - Remove the "Please try porting your programs" request now that Eio is stable. - Use a simpler and more typical example for the switches section. - In the `Executor_pool` make the second example create the pool the same way as the first one (and shrink it a bit). - Replace out-of-date retro-httpaf-bench example with cohttp-eio and capnp-rpc examples. - In `Net.run_server`, suggest using `Executor_pool`. --- README.md | 63 ++-- doc/traces/switch-mock.fxt | Bin 2328 -> 2296 bytes doc/traces/switch-mock.svg | 717 ++++++++++++++++++------------------- lib_eio/net.mli | 3 + 4 files changed, 368 insertions(+), 415 deletions(-) diff --git a/README.md b/README.md index cce5024da..ef3a22c43 100644 --- a/README.md +++ b/README.md @@ -79,8 +79,7 @@ Additionally, modern operating systems provide high-performance alternatives to For example, Linux's io_uring system has applications write the operations they want to perform to a ring buffer, which Linux handles asynchronously, and Eio can take advantage of this. -Please try porting your programs to use Eio and submit PRs or open issues when you find problems. -Remember that you can always [fall back to using Lwt libraries](#lwt) to provide missing features if necessary. +You can always [fall back to using Lwt libraries](#lwt) to provide missing features if necessary. See [Awesome Multicore OCaml][] for links to work migrating other projects to Eio. ## Eio packages @@ -232,12 +231,7 @@ The green segments show when each fiber is running. Note that the output from `traceln` appears in the trace as well as on the console. In the eio-trace window, scrolling with the mouse or touchpad will zoom in or out of the diagram. -There are various third-party tools that can also consume this data -(but may currently require patches to support the new system): - -- [Meio][] (Monitoring for Eio) provides an interactive console-based UI for exploring running fibers. -- [Olly][] can save Perfetto traces and report statistics. - +Third-party tools, such as [Olly][], can also consume this data. [examples/trace](./examples/trace/) shows how to consume the events manually. ## Cancellation @@ -311,22 +305,23 @@ For example: ```ocaml # Eio_main.run @@ fun _env -> Switch.run (fun sw -> - Fiber.fork ~sw - (fun () -> for i = 1 to 3 do traceln "i = %d" i; Fiber.yield () done); - traceln "First thread forked"; - Fiber.fork ~sw - (fun () -> for j = 1 to 3 do traceln "j = %d" j; Fiber.yield () done); - traceln "Second thread forked; top-level code is finished" - ); + for i = 1 to 3 do + Fiber.fork ~sw (fun () -> + traceln "Job %d starting" i; + Fiber.yield (); + traceln "%d done" i; + ); + done; + traceln "All child fibers forked"; + ); traceln "Switch is finished";; -+i = 1 -+First thread forked -+j = 1 -+Second thread forked; top-level code is finished -+i = 2 -+j = 2 -+i = 3 -+j = 3 ++Job 1 starting ++Job 2 starting ++Job 3 starting ++All child fibers forked ++1 done ++2 done ++3 done +Switch is finished - : unit = () ``` @@ -1015,12 +1010,8 @@ Usually you will only want one pool for an entire application, so the pool is ty let () = Eio_main.run @@ fun env -> Switch.run @@ fun sw -> - let pool = - Eio.Executor_pool.create - ~sw (Eio.Stdenv.domain_mgr env) - ~domain_count:4 - in - main ~pool + let dm = Eio.Stdenv.domain_mgr env in + main ~pool:(Eio.Executor_pool.create ~sw ~domain_count:2 dm) ``` The pool starts its domain workers immediately upon creation. @@ -1034,11 +1025,7 @@ The total number of domains should not exceed `Domain.recommended_domain_count` We can run the previous example using an Executor Pool like this: ```ocaml -let main ~domain_mgr = - Switch.run @@ fun sw -> - let pool = - Eio.Executor_pool.create ~sw domain_mgr ~domain_count:4 - in +let main ~pool = let test n = traceln "sum 1..%d = %d" n (Eio.Executor_pool.submit_exn pool ~weight:1.0 @@ -1052,7 +1039,9 @@ let main ~domain_mgr = ```ocaml # Eio_main.run @@ fun env -> - main ~domain_mgr:(Eio.Stdenv.domain_mgr env);; + Switch.run @@ fun sw -> + let dm = Eio.Stdenv.domain_mgr env in + main ~pool:(Eio.Executor_pool.create ~sw ~domain_count:2 dm) +Starting CPU-intensive task... +Starting CPU-intensive task... +Finished @@ -1632,7 +1621,8 @@ It can then be used like any other Eio flow: ## Example Applications - [gemini-eio][] is a simple Gemini browser. It shows how to integrate Eio with `ocaml-tls` and `notty`. -- [ocaml-multicore/retro-httpaf-bench](https://github.com/ocaml-multicore/retro-httpaf-bench) includes a simple HTTP server using Eio. It shows how to use Eio with `httpaf`, and how to use multiple domains for increased performance. +- [cohttp-eio/examples](https://github.com/mirage/ocaml-cohttp/tree/master/cohttp-eio/examples) shows how to use Eio with HTTP. +- [capnp-rpc](https://github.com/mirage/capnp-rpc) shows how to use Eio with Cap'n Proto. - [Awesome Multicore OCaml][] lists many other projects. ## Integrations @@ -1906,7 +1896,6 @@ Some background about the effects system can be found in: [Eio.Condition]: https://ocaml-multicore.github.io/eio/eio/Eio/Condition/index.html [Domainslib]: https://github.com/ocaml-multicore/domainslib [kcas]: https://github.com/ocaml-multicore/kcas -[Meio]: https://github.com/tarides/meio [Lambda Capabilities]: https://roscidus.com/blog/blog/2023/04/26/lambda-capabilities/ [Eio.Process]: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html [Dev meetings]: https://docs.google.com/document/d/1ZBfbjAkvEkv9ldumpZV5VXrEc_HpPeYjHPW_TiwJe4Q diff --git a/doc/traces/switch-mock.fxt b/doc/traces/switch-mock.fxt index b61b2320c292514994417ee07b556d0e370a0d01..f1154c9cfb33e4e92f3d473516f324ff5968158d 100644 GIT binary patch literal 2296 zcmZ`)OKTHR6#kmDTKmvyYph1wVOmfGtDRVpf}+J2K0wfoE-Y~}wnJkk&WuzMQE}x$ z(S?GF8*$N%JMjSuZglC=A0Q|$)IZ?H^T_FtN^U}u^SI}H=bP`|^r8LGmD2^dXv1;< z^*Hi_Bq2M84zlC0HnW4i4mC$ z;k>Y-c`laGP9VKn57^@pDz@V&O4aU^K7Rc&n@Hicr|T9iMn{?9kf^-IDIU_2W>7u|w2nGaKcR(QxU4`1Fl^T6ElVjjBb`+pvK zG9F68Ll5(?Qg*fG;p9i{!_S--%}f2eV1Ap|;x@10v3dV2spFzoo)qb5EUA}kE+OIP zm&Rp3sMbhFTG9A0oTJF)dnvc;tKxF8N;0d_jNo(8Cv`58xXUvEJgk-(k4ER6aVJU3 zaY{-DcA_tzr@ae5v`&Hct)>cV=*4RkdFlh47?>8ldFU5j1@Gmg9@JFGjHjRS9uzds z=A9f=+jQV!Ame|h@IS!(Yq!??zaG*$d^UI)|K>OTE#8X%eZ$RlN)25azlMY6X=i@7 zk7&M!wTt|D&HS}9e^0h*9`m=B@DXpcANaIG{alavc{r}N@iXM9o$R#QpAD-ON3NvA zxeL51~A=X4d$%xOONAJqO-2RI&Co%N#oQ*ytImFLT0IvrN30p;-GzWrE_$xE7V z_(o&3?cDQu;W^At`{bO~Qq6O*L7wlpQ;BL++|J*gYZ_;K8>F9}yL~s*@1aPy4gKF- z3DfM>1rEshE#l=(&9mohcns&>TN=0X!TMyJ<|mw@_g%L&&&5W;>18-Y=MU~^oN;bc zoTBrIyXq%Alvl)|dukgV>uY%KH{zx<)&t`)Kj9I59lLLMHVK|mhDUUD;8BKWlj0Fw zy?eZfhw_T}{-ha?^))<4o@zYPSzeyE`3ax=-zD&u>3>L_*&P4Bf3b^`RQs_SX%uGzw zixvu{c+u-3rKR+y-WB`-{sb?*>Q#|~-sweAsPTNv*>P7g3A=mFd*0_f&pGFPXB35n z&2LI@F@RkFI#KBPaZGj&JIIcL_UZ}xK8swALik^vqv@}QpX?OdMV|fuKL}I1KnQ^6 ziHTZYyy3W%h2w&z#<|#u0{u*GcYOA^#ER`G3=_3?OCGPY&L$F62l5ngQn#6 zWKsfW-l6tm7Nhw*?Ya9v_m?PsjQsoPkDqDe2_Ja*kFHlylzIx!^|<4=b%2>ik>Zw~ zYMkkO@UPm|e~Qa7-(%0zU&nqz1QvoQPMlBO84_wt38%I_K6e<3aihtbc6F zc$cIf*Ry^USnnS@ev@;}dP~HM`at`D@}T+|hwJuNYFoX_L%QBy@AYBzN0`AaXKNnV%&&pT`>; zjUZVLnk~81BtDlbQq0wo#vAXiC)Boc!*j>_%+K@1b^B;i<6KO3=eSC7Hpj&&UFW(@ zDnFUueXjZ$hjG76ZOgxv+SX^TH^-UZ`u5AT-g z8MQ6{qtx!#Z+_E%`cun)u&cjDc})M4*)0D-%`f_Y_^g{>^#7gOmjA+>uJ`LVzv+KC zZ~4nz{b_#Df9Fh=zxIXbE&rPZUGLX#{wgYT%hG#xGf1+x4e*8BUln}! zrS7-$YB+}fJYDbCXMVyV{uTWHRWFXk8_xN2x}Ke{yv(!tX>R0ww0vIUsBUuKwJ)e$ z$050s^nAQ~!bluFcFz7>)OeobL*!>%KL5iP)lYmWPX#~SRNHhLFBent23_?S6{y0I Y`o+n{a*OU*KT<#O8 - + @@ -81,489 +81,450 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - - - - - - - - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - - - - - - - - - + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - + + + + + + + + + + + + - - - - - - - - + + + + + + + + + + + + + + + + + - - - - - + + + + + + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - + + + + + + + + - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + diff --git a/lib_eio/net.mli b/lib_eio/net.mli index 78761316f..154a8d587 100644 --- a/lib_eio/net.mli +++ b/lib_eio/net.mli @@ -231,6 +231,9 @@ val run_server : In such cases you must ensure that [connection_handler] only accesses thread-safe values. Note that having more than {!Domain.recommended_domain_count} domains in total is likely to result in bad performance. + For services that are bottlenecked on CPU rather than IO, + you can run a single accept loop and have the handler submit CPU-intensive jobs to an {!module:Executor_pool}. + @param max_connections The maximum number of concurrent connections accepted by [s] at any time. The default is [Int.max_int]. @param stop Resolving this promise causes [s] to stop accepting new connections.