From 59814f61b1ba746873e63866898769c0a0615c65 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Mon, 5 Feb 2024 15:00:24 +0000 Subject: [PATCH 1/3] Remove out-of-date performance section from README It relies on the `splice` optimisation, which is currently disabled, and encourages `Flow.copy`, which is often a bad choice as you can't control the buffer size. --- README.md | 55 ------------------------------------------------------- 1 file changed, 55 deletions(-) diff --git a/README.md b/README.md index 3d10d7260..16f78595b 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,6 @@ Eio replaces existing concurrency libraries such as Lwt * [Cancellation](#cancellation) * [Racing](#racing) * [Switches](#switches) -* [Performance](#performance) * [Networking](#networking) * [Design Note: Capabilities](#design-note-capabilities) * [Buffered Reading and Parsing](#buffered-reading-and-parsing) @@ -358,60 +357,6 @@ Every switch also creates a new cancellation context. You can use `Switch.fail` to mark the switch as failed and cancel all fibers within it. The exception (or exceptions) passed to `fail` will be raised by `run` when the fibers have exited. -## Performance - -As mentioned above, Eio allows you to supply your own implementations of its abstract interfaces. -This is in contrast to OCaml's standard library, which only operates on OS file descriptors. -You might wonder what the performance impact of this is. -Here's a simple implementation of `cat` using the standard OCaml functions: - -```ocaml -# let () = - let buf = Bytes.create 4096 in - let rec copy () = - match input stdin buf 0 4096 with - | 0 -> () - | got -> - output stdout buf 0 got; - copy () - in - copy ();; -``` - -And here is the equivalent using Eio: - - -```ocaml -# let () = - Eio_main.run @@ fun env -> - Eio.Flow.copy - (Eio.Stdenv.stdin env) - (Eio.Stdenv.stdout env);; -``` - -Testing on a fresh 10G file with [pv](https://www.ivarch.com/programs/pv.shtml) on my machine gives: - -``` -$ truncate -s 10G dummy - -$ cat_ocaml_unix.exe /dev/null -10.0GiB 0:00:04 [2.33GiB/s] - -$ cat /dev/null -10.0GiB 0:00:04 [2.42GiB/s] - -$ cat_ocaml_eio.exe /dev/null -10.0GiB 0:00:03 [3.01GiB/s] -``` - -`Eio.Flow.copy src dst` asks `dst` to copy from `src`. -As `dst` here wraps a Unix file descriptor, -it first calls the `probe` method on the `src` object to check whether it does too. -Discovering that `src` is also wrapping a file descriptor, it switches to a faster code path optimised for that case. -On my machine, this code path uses the Linux-specific `splice` system call for maximum performance. - -Note that not all cases are well-optimised yet, but the idea is for each backend to choose the most efficient way to implement the operation. - ## Networking Eio provides an API for [networking][Eio.Net]. From 1cbcda0ce141980ad9c1eb0ca8b1e8c7bfaa47e3 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Wed, 21 Feb 2024 10:27:59 +0000 Subject: [PATCH 2/3] Illustrate switch example --- README.md | 4 + doc/traces/Makefile | 2 +- doc/traces/both-posix.svg | 297 +++++++++---------- doc/traces/switch-mock.fxt | Bin 0 -> 2328 bytes doc/traces/switch-mock.svg | 569 +++++++++++++++++++++++++++++++++++++ 5 files changed, 712 insertions(+), 160 deletions(-) create mode 100644 doc/traces/switch-mock.fxt create mode 100644 doc/traces/switch-mock.svg diff --git a/README.md b/README.md index 16f78595b..79bd33971 100644 --- a/README.md +++ b/README.md @@ -335,6 +335,10 @@ For example: - : unit = () ``` +

+ +

+ `Switch.run fn` creates a new switch `sw` and runs `fn sw`. `fn` may spawn new fibers and attach them to the switch. It may also attach other resources such as open file handles. diff --git a/doc/traces/Makefile b/doc/traces/Makefile index 20a95cfcc..81823bc70 100644 --- a/doc/traces/Makefile +++ b/doc/traces/Makefile @@ -1,4 +1,4 @@ -all: both-posix.svg cancel-posix.svg +all: both-posix.svg cancel-posix.svg switch-mock.svg %.svg: %.fxt eio-trace render -f "$<" "$@" diff --git a/doc/traces/both-posix.svg b/doc/traces/both-posix.svg index 28c5c0f68..7c584bba1 100644 --- a/doc/traces/both-posix.svg +++ b/doc/traces/both-posix.svg @@ -3,123 +3,102 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - - - + - - - - - - - - - - + - + - - - - - - - - - - + - + - + - + - + - + - + - + - + - + - + - + @@ -168,31 +147,31 @@ - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + @@ -201,13 +180,13 @@ - - - - - - - + + + + + + + @@ -216,13 +195,13 @@ - - - - - - - + + + + + + + @@ -231,13 +210,13 @@ - - - - - - - + + + + + + + @@ -245,24 +224,24 @@ - - - - - + + + + + - - - - - - - + + + + + + + @@ -270,13 +249,13 @@ - - - - - - - + + + + + + + @@ -285,13 +264,13 @@ - - - - - - - + + + + + + + @@ -301,71 +280,71 @@ - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - + + + + diff --git a/doc/traces/switch-mock.fxt b/doc/traces/switch-mock.fxt new file mode 100644 index 0000000000000000000000000000000000000000..b61b2320c292514994417ee07b556d0e370a0d01 GIT binary patch literal 2328 zcmZ`)U27C)6n?V1e&oZNxMtJnu9=Pjr8QP}0}a(6EG4$06p|u{NL*(p$>_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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From c2f22d85eb63e2823da98ec441b447a8e7780691 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Wed, 21 Feb 2024 10:35:49 +0000 Subject: [PATCH 3/3] Illustrate network example --- README.md | 13 +- doc/traces/Makefile | 2 +- doc/traces/net-posix.fxt | Bin 0 -> 3080 bytes doc/traces/net-posix.svg | 832 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 841 insertions(+), 6 deletions(-) create mode 100644 doc/traces/net-posix.fxt create mode 100644 doc/traces/net-posix.svg diff --git a/README.md b/README.md index 79bd33971..d21318a98 100644 --- a/README.md +++ b/README.md @@ -392,15 +392,14 @@ Here is a client that connects to address `addr` using network `net` and reads a ```ocaml let run_client ~net ~addr = + Switch.run ~name:"client" @@ fun sw -> traceln "Client: connecting to server"; - Switch.run @@ fun sw -> let flow = Eio.Net.connect ~sw net addr in - let b = Buffer.create 100 in - Eio.Flow.copy flow (Eio.Flow.buffer_sink b); - traceln "Client: received %S" (Buffer.contents b) + traceln "Client: received %S" (Eio.Flow.read_all flow) ``` Note: the `flow` is attached to `sw` and will be closed automatically when it finishes. +We also named the switch here; this will appear in the trace output (see below). This can also be tested on its own using a mock network: @@ -439,7 +438,7 @@ We can now run the client and server together using the real network (in a singl ```ocaml let main ~net ~addr = - Switch.run @@ fun sw -> + Switch.run ~name:"main" @@ fun sw -> let server = Eio.Net.listen net ~sw ~reuse_addr:true ~backlog:5 addr in Fiber.fork_daemon ~sw (fun () -> run_server server); run_client ~net ~addr @@ -460,6 +459,10 @@ the test would never finish. - : unit = () ``` +

+ +

+ See [examples/net](./examples/net/) for a more complete example. ## Design Note: Capabilities diff --git a/doc/traces/Makefile b/doc/traces/Makefile index 81823bc70..1f8a478b1 100644 --- a/doc/traces/Makefile +++ b/doc/traces/Makefile @@ -1,4 +1,4 @@ -all: both-posix.svg cancel-posix.svg switch-mock.svg +all: both-posix.svg cancel-posix.svg switch-mock.svg net-posix.svg %.svg: %.fxt eio-trace render -f "$<" "$@" diff --git a/doc/traces/net-posix.fxt b/doc/traces/net-posix.fxt new file mode 100644 index 0000000000000000000000000000000000000000..fd4d89b5adb17ef2b2e11ddd11d1a9208eb715bb GIT binary patch literal 3080 zcmai0O>7%g5T4jc+BhvqLld0lhs|r67DS_BBN3Gg;$Kv#D2WJ!O2Jvbgq56Kv);t5 zpe-jrLL5Ni??MGqd#H$LdZma195^+o5|DD?g!nTGt;&T;i23n&S)+(eWc!;pZ)V;% z-+OPnq4kmD(|ur|1-1b|ISgD|sUS{48{*LO7Z2h0qmW9W3;pwRp#E!QNU(u4{sCAo zV1t2Hi~!)eGM;bp*Ej~Vke^o+KLhPJ6CgTKwq!9_72z-lBEj1^k6T_Q2odC3(&%w) za^|P|G3b7-nuqwK5986g_QLkqh`$VU;0VBiH*dqcd3_yJBH8F^Uf+b6odeU7N9)f) z26o_>8`?r-4{|tiErNq}WkCJ4E}gfZS0zE|Q{!KsO~%hNI{?bF)@PuTYpqnh$bFu9 zND&X+^GP0vTY89xPW=8a4?DP$rGn>^-x#E5IrXf>)6STuJoB`Zc)Eq0@Y#x|?=MRo zqzQVE53DZ(YF9pVT=~#?m5-b2$vAoLe$0o~fjUUj`ro^nTt8`to~_oO!wzHU{gfnD4Ox8zwLcLMfl7bVtt26|ZGTwl518@QEqAB6?imVChaQaxz<1Krj0*;pQ(aT9`z}265y;&Ue^x1K+o9gr|WM1y0P=J_lP%vHg4Z5jEae)XWObh;52F+lzu!3Orky1$oozlU@`j6U>i zrTdPvGM~;IdQkVM%M7Spb+6;9d)1k)Cwnd#Ctp7=^c>JSa2>7G*UJ~ge;x*K&jL)b zmJd6NLDcA7;5!Rpu;i$Qs6OmpEA{WWOERDOH-L8J590z{yDE0dL;7C(Rj}6ia!qi| zyX=E^HyiV~Uw2(oEd6`!Ml#O8pMrItkbX!XYRCMD0nTS;SudLZSf^m+lj z{s0d#ufx!OLHwHguJvcvWIX0ibgOpE&pLhTqUI-l`(fL912ey$T~RFje)_Fo&2!{C z!AX7r)NbH*x$kYEh&1v3>_J=aMk6lo=NmsOmVSh_2Ie~6{#~)uF|#RH>o`-#&2^}q z`b>F;|7gVFyf0o?EazD7UxMes!CK>UDzvWkR&3ERkJ(Zw5W&lFMcab(&ga!;`?HPn z%0WBnjr4xXh~2;lpI7)k6ydo??-_h^7R+E0C}pmTc!=QrQ4vYsL6xI^Y?o{5t& zrh9AlR1$x6TCl<0Oz&Yf41*BAbC`kd@u{d-^5(}MM%f_(nCAP{z=>C6p4O-LDeddM z|MI)}YSK^7AN6|x8KDbiir+8B3)O-b&3VNVzm%b!*42fdwb!+7Ij28)L$UNf`=(&+ zf7@GvlX~w5wIe@#4xg+05hi}BXJj7kE5yU_{)d8fopC&=W9B0n$N8*F|8v1w$KQ3F z)Zr+oUHjetMKVtZuAQF$>-UdeHuAHs2G?Uu>sf8W(bqDL>qDIl!+lqhdE+`s|3mQ7 sMjVfHd-Mmv2KMp0+oH>5qF%=Me5yp%xf1SeeZRr}wd}*OLp7QA52xIu9RL6T literal 0 HcmV?d00001 diff --git a/doc/traces/net-posix.svg b/doc/traces/net-posix.svg new file mode 100644 index 000000000..9c534923b --- /dev/null +++ b/doc/traces/net-posix.svg @@ -0,0 +1,832 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +