commit 40453a8593bfacaeb58d7b9bbeed9be67309da5f · anil.recoil.org/ocaml-fastcgi

CLAUDE.md

···

       1
       +
       This branch exists to figure out an OCaml specification for the FastCGI interface.

     

       2
       +
       

     

       3
       +
       The spec for the FastCGI protocol is in spec/FastCGI_Specification.html.

     

       4
       +
       The Go lang implementation of FastCGI is in spec/fcgi.go.

     

       5
       +
       

     

       6
       +
       Both of these are intended to act as a reference implementation, for us to figure out what the ideal OCaml interface should look like for FastCGI.

     

       7
       +
       

     

       8
       +
       Our target language is OCaml, using the Eio library. The README for Eio is in OCaml-EIO-README.md to give you a reference.

+735

spec/FastCGI_Specification.html

···

       1
       +
       <!DOCTYPE html>

     

       2
       +
       <html lang="en-us">

     

       3
       +
         <head>

     

       4
       +
           <meta charset="UTF-8">

     

       5
       +
           <title>FastCGI Specification</title>

     

       6
       +
           <meta name="description" content="This specification has narrow goal is to specify, from an application perspective, the interface between a FastCGI application and a Web server that supports FastCGI."/>

     

       7
       +
           <meta name="keywords" content="fastcgi, fastcgi specification, fastcgi source, fastcgi php, fastcgi apache, fastcgi iis, fastcgi c++, fastcgi nginx, fastcgi download, fcgi spec, fcgi-spec, fastcgi overview, cgi, protocol specification, php-fpm, apache, mod_proxy_fastcgi, mod_fcgid, mod_fastcgi, fcgi2, fcgi sdk, nginx fastcgi, ngx_http_fastcgi_module, ligthttpd, cherokee, perl, python, ruby"/>

     

       8
       +
           <meta name="viewport" content="width=device-width, initial-scale=1">

     

       9
       +
           <meta name="theme-color" content="#157878">

     

       10
       +
           <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700' rel='stylesheet' type='text/css'>

     

       11
       +
           <link rel="stylesheet" href="/assets/css/style.css?v=cfbb93ce861c9fb058b2d12ee0a83e55a1682c1f">

     

       12
       +
         </head>

     

       13
       +
         <body>

     

       14
       +
           <section class="page-header">

     

       15
       +
             <h1 class="project-name">FastCGI Specification</h1>

     

       16
       +
             <h2 class="project-tagline">This specification has narrow goal is to specify, from an application perspective, the interface between a FastCGI application and a Web server that supports FastCGI.</h2>

     

       17
       +
             

     

       18
       +
               <a href="https://github.com/FastCGI-Archives" class="btn">View on GitHub</a>

     

       19
       +
             

     

       20
       +
           </section>

     

       21
       +
       

     

       22
       +
           <section class="main-content">

     

       23
       +
             <p><a href="https://www.linkedin.com/in/mark-brown-32a01b11/">Mark R. Brown</a></p>

     

       24
       +
       

     

       25
       +
       <p>Open Market, Inc.</p>

     

       26
       +
       

     

       27
       +
       <p>Document Version: 1.0<br />

     

       28
       +
       29 April 1996</p>

     

       29
       +
       

     

       30
       +
       <h5 id="copyright--1996-open-market-inc-245-first-street-cambridge-ma-02142-usa">Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.</h5>

     

       31
       +
       

     

       32
       +
       <hr />

     

       33
       +
       

     

       34
       +
       <ul>

     

       35
       +
         <li><a href="#S1">1. Introduction</a></li>

     

       36
       +
         <li><a href="#S2">2. Initial Process State</a>

     

       37
       +
           <ul>

     

       38
       +
             <li><a href="#S2.1">2.1 Argument list</a></li>

     

       39
       +
             <li><a href="#S2.2">2.2 File descriptors</a></li>

     

       40
       +
             <li><a href="#S2.3">2.3 Environment variables</a></li>

     

       41
       +
             <li><a href="#S2.4">2.4 Other state</a></li>

     

       42
       +
           </ul>

     

       43
       +
         </li>

     

       44
       +
         <li><a href="#S3">3. Protocol Basics</a>

     

       45
       +
           <ul>

     

       46
       +
             <li><a href="#S3.1">3.1 Notation</a></li>

     

       47
       +
             <li><a href="#S3.2">3.2 Accepting Transport Connections</a></li>

     

       48
       +
             <li><a href="#S3.3">3.3 Records</a></li>

     

       49
       +
             <li><a href="#S3.4">3.4 Name-Value Pairs</a></li>

     

       50
       +
             <li><a href="#S3.5">3.5 Closing Transport Connections</a></li>

     

       51
       +
           </ul>

     

       52
       +
         </li>

     

       53
       +
         <li><a href="#S4">4. Management Record Types</a>

     

       54
       +
           <ul>

     

       55
       +
             <li><a href="#S4.1">4.1 <tt>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</tt></a></li>

     

       56
       +
             <li><a href="#S4.2">4.2 <tt>FCGI_UNKNOWN_TYPE</tt></a></li>

     

       57
       +
           </ul>

     

       58
       +
         </li>

     

       59
       +
         <li><a href="#S5">5. Application Record Types</a>

     

       60
       +
           <ul>

     

       61
       +
             <li><a href="#S5.1">5.1 <tt>FCGI_BEGIN_REQUEST</tt></a></li>

     

       62
       +
             <li><a href="#S5.2">5.2 Name-Value Pair Streams: <tt>FCGI_PARAMS</tt>, <tt>FCGI_RESULTS</tt></a></li>

     

       63
       +
             <li><a href="#S5.3">5.3 Byte Streams: <tt>FCGI_STDIN</tt>, <tt>FCGI_DATA</tt>, <tt>FCGI_STDOUT</tt>, <tt>FCGI_STDERR</tt></a></li>

     

       64
       +
             <li><a href="#S5.4">5.4 <tt>FCGI_ABORT_REQUEST</tt></a></li>

     

       65
       +
             <li><a href="#S5.5">5.5 <tt>FCGI_END_REQUEST</tt></a></li>

     

       66
       +
           </ul>

     

       67
       +
         </li>

     

       68
       +
         <li><a href="#S6">6. Roles</a>

     

       69
       +
           <ul>

     

       70
       +
             <li><a href="#S6.1">6.1 Role Protocols</a></li>

     

       71
       +
             <li><a href="#S6.2">6.2 Responder</a></li>

     

       72
       +
             <li><a href="#S6.3">6.3 Authorizer</a></li>

     

       73
       +
             <li><a href="#S6.4">6.4 Filter</a></li>

     

       74
       +
           </ul>

     

       75
       +
         </li>

     

       76
       +
         <li><a href="#S7">7. Errors</a></li>

     

       77
       +
         <li><a href="#S8">8. Types and Constants</a></li>

     

       78
       +
         <li><a href="#S9">9. References</a></li>

     

       79
       +
         <li><a href="#SA">A. Table: Properties of the record types</a></li>

     

       80
       +
         <li><a href="#SB">B. Typical Protocol Message Flow</a></li>

     

       81
       +
       </ul>

     

       82
       +
       

     

       83
       +
       <hr />

     

       84
       +
       

     

       85
       +
       <h3 id="1-introduction"><a name="S1">1. Introduction</a></h3>

     

       86
       +
       

     

       87
       +
       <p>FastCGI is an open extension to CGI that provides high performance for all Internet applications without the penalties of Web server APIs.</p>

     

       88
       +
       

     

       89
       +
       <p>This specification has narrow goal: to specify, from an application perspective, the interface between a FastCGI application and a Web server that supports FastCGI. Many Web server features related to FastCGI, e.g. application management facilities, have nothing to do with the application to Web server interface, and are not described here.</p>

     

       90
       +
       

     

       91
       +
       <p>This specification is for Unix (more precisely, for POSIX systems that support Berkeley Sockets). The bulk of the specification is a simple communications protocol that is independent of byte ordering and will extend to other systems.</p>

     

       92
       +
       

     

       93
       +
       <p>We’ll introduce FastCGI by comparing it with conventional Unix implementations of CGI/1.1. FastCGI is designed to support long-lived application processes, i.e. <em>application servers</em>. That’s a major difference compared with conventional Unix implementations of CGI/1.1, which construct an application process, use it respond to one request, and have it exit.</p>

     

       94
       +
       

     

       95
       +
       <p>The initial state of a FastCGI process is more spartan than the initial state of a CGI/1.1 process, because the FastCGI process doesn’t begin life connected to anything. It doesn’t have the conventional open files <tt>stdin</tt>, <tt>stdout</tt>, and <tt>stderr</tt>, and it doesn’t receive much information through environment variables. The key piece of initial state in a FastCGI process is a listening socket, through which it accepts connections from a Web server.</p>

     

       96
       +
       

     

       97
       +
       <p>After a FastCGI process accepts a connection on its listening socket, the process executes a simple protocol to receive and send data. The protocol serves two purposes. First, the protocol multiplexes a single transport connection between several independent FastCGI requests. This supports applications that are able to process concurrent requests using event-driven or multi-threaded programming techniques. Second, within each request the protocol provides several independent data streams in each direction. This way, for instance, both <tt>stdout</tt> and <tt>stderr</tt> data pass over a single transport connection from the application to the Web server, rather than requiring separate pipes as with CGI/1.1.</p>

     

       98
       +
       

     

       99
       +
       <p>A FastCGI application plays one of several well-defined <em>roles</em>. The most familiar is the <em>Responder</em> role, in which the application receives all the information associated with an HTTP request and generates an HTTP response; that’s the role CGI/1.1 programs play. A second role is <em>Authorizer</em>, in which the application receives all the information associated with an HTTP request and generates an authorized/unauthorized decision. A third role is <em>Filter</em>, in which the application receives all the information associated with an HTTP request, plus an extra stream of data from a file stored on the Web server, and generates a “filtered” version of the data stream as an HTTP response. The framework is extensible so that more FastCGI can be defined later.</p>

     

       100
       +
       

     

       101
       +
       <p>In the remainder of this specification the terms “FastCGI application,” “application process,” or “application server” are abbreviated to “application” whenever that won’t cause confusion.</p>

     

       102
       +
       

     

       103
       +
       <h3 id="2-initial-process-state"><a name="S2">2. Initial Process State</a></h3>

     

       104
       +
       

     

       105
       +
       <h4 id="21-argument-list"><a name="S2.1">2.1 Argument list</a></h4>

     

       106
       +
       

     

       107
       +
       <p>By default the Web server creates an argument list containing a single element, the name of the application, taken to be the last component of the executable’s path name. The Web server may provide a way to specify a different application name, or a more elaborate argument list.</p>

     

       108
       +
       

     

       109
       +
       <p>Note that the file executed by the Web server might be an interpreter file (a text file that starts with the characters <tt>#!</tt>), in which case the application’s argument list is constructed as described in the <tt>execve</tt> manpage.</p>

     

       110
       +
       

     

       111
       +
       <h4 id="22-file-descriptors"><a name="S2.2">2.2 File descriptors</a></h4>

     

       112
       +
       

     

       113
       +
       <p>The Web server leaves a single file descriptor, <tt>FCGI_LISTENSOCK_FILENO</tt>, open when the application begins execution. This descriptor refers to a listening socket created by the Web server.</p>

     

       114
       +
       

     

       115
       +
       <p><tt>FCGI_LISTENSOCK_FILENO</tt> equals <tt>STDIN_FILENO</tt>. The standard descriptors <tt>STDOUT_FILENO</tt> and <tt>STDERR_FILENO</tt> are closed when the application begins execution. A reliable method for an application to determine whether it was invoked using CGI or FastCGI is to call <tt>getpeername(FCGI_LISTENSOCK_FILENO)</tt>, which returns -1 with <tt>errno</tt> set to <tt>ENOTCONN</tt> for a FastCGI application.</p>

     

       116
       +
       

     

       117
       +
       <p>The Web server’s choice of reliable transport, Unix stream pipes (<tt>AF_UNIX</tt>) or TCP/IP (<tt>AF_INET</tt>), is implicit in the internal state of the <tt>FCGI_LISTENSOCK_FILENO</tt> socket.</p>

     

       118
       +
       

     

       119
       +
       <h4 id="23-environment-variables"><a name="S2.3">2.3 Environment variables</a></h4>

     

       120
       +
       

     

       121
       +
       <p>The Web server may use environment variables to pass parameters to the application. This specification defines one such variable, <tt>FCGI_WEB_SERVER_ADDRS</tt>; we expect more to be defined as the specification evolves. The Web server may provide a way to bind other environment variables, such as the <tt>PATH</tt> variable.</p>

     

       122
       +
       

     

       123
       +
       <h4 id="24-other-state"><a name="S2.4">2.4 Other state</a></h4>

     

       124
       +
       

     

       125
       +
       <p>The Web server may provide a way to specify other components of an application’s initial process state, such as the priority, user ID, group ID, root directory, and working directory of the process.</p>

     

       126
       +
       

     

       127
       +
       <h3 id="3-protocol-basics"><a name="S3">3. Protocol Basics</a></h3>

     

       128
       +
       

     

       129
       +
       <h4 id="31-notation"><a name="S3.1">3.1 Notation</a></h4>

     

       130
       +
       

     

       131
       +
       <p>We use C language notation to define protocol message formats. All structure elements are defined in terms of the <tt>unsigned char</tt> type, and are arranged so that an ISO C compiler lays them out in the obvious manner, with no padding. The first byte defined in the structure is transmitted first, the second byte second, etc.</p>

     

       132
       +
       

     

       133
       +
       <p>We use two conventions to abbreviate our definitions.</p>

     

       134
       +
       

     

       135
       +
       <p>First, when two adjacent structure components are named identically except for the suffixes “<tt>B1</tt>” and “<tt>B0</tt>,” it means that the two components may be viewed as a single number, computed as <tt>B1«8 + B0</tt>. The name of this single number is the name of the components, minus the suffixes. This convention generalizes in an obvious way to handle numbers represented in more than two bytes.</p>

     

       136
       +
       

     

       137
       +
       <p>Second, we extend C <tt>struct</tt>s to allow the form</p>

     

       138
       +
       

     

       139
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        struct {

     

       140
       +
                   unsigned char mumbleLengthB1;

     

       141
       +
                   unsigned char mumbleLengthB0;

     

       142
       +
                   ... /* other stuff */

     

       143
       +
                   unsigned char mumbleData[mumbleLength];

     

       144
       +
               };

     

       145
       +
       </code></pre></div></div>

     

       146
       +
       

     

       147
       +
       <p>meaning a structure of varying length, where the length of a component is determined by the values of the indicated earlier component or components.</p>

     

       148
       +
       

     

       149
       +
       <h4 id="32-accepting-transport-connections"><a name="S3.2">3.2 Accepting Transport Connections</a></h4>

     

       150
       +
       

     

       151
       +
       <p>A FastCGI application calls <tt>accept()</tt> on the socket referred to by file descriptor <tt>FCGI_LISTENSOCK_FILENO</tt> to accept a new transport connection. If the <tt>accept()</tt> succeeds, and the <tt>FCGI_WEB_SERVER_ADDRS</tt> environment variable is bound, the application application immediately performs the following special processing:</p>

     

       152
       +
       

     

       153
       +
       <ul>

     

       154
       +
         <li>

     

       155
       +
           <p><tt>FCGI_WEB_SERVER_ADDRS</tt>: The value is a list of valid IP addresses for the Web server.</p>

     

       156
       +
       

     

       157
       +
           <p>If <tt>FCGI_WEB_SERVER_ADDRS</tt> was bound, the application checks the peer IP address of the new connection for membership in the list. If the check fails (including the possibility that the connection didn’t use TCP/IP transport), the application responds by closing the connection.</p>

     

       158
       +
       

     

       159
       +
           <p><tt>FCGI_WEB_SERVER_ADDRS</tt> is expressed as a comma-separated list of IP addresses. Each IP address is written as four decimal numbers in the range [0..255] separated by decimal points. So one legal binding for this variable is <tt>FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71</tt>.</p>

     

       160
       +
         </li>

     

       161
       +
       </ul>

     

       162
       +
       

     

       163
       +
       <p>An application may accept several concurrent transport connections, but it need not do so.</p>

     

       164
       +
       

     

       165
       +
       <h4 id="33-records"><a name="S3.3">3.3 Records</a></h4>

     

       166
       +
       

     

       167
       +
       <p>Applications execute requests from a Web server using a simple protocol. Details of the protocol depend upon the application’s role, but roughly speaking the Web server first sends parameters and other data to the application, then the application sends result data to the Web server, and finally the application sends the Web server an indication that the request is complete.</p>

     

       168
       +
       

     

       169
       +
       <p>All data that flows over the transport connection is carried in <em>FastCGI records</em>. FastCGI records accomplish two things. First, records multiplex the transport connection between several independent FastCGI requests. This multiplexing supports applications that are able to process concurrent requests using event-driven or multi-threaded programming techniques. Second, records provide several independent data streams in each direction within a single request. This way, for instance, both <tt>stdout</tt> and <tt>stderr</tt> data can pass over a single transport connection from the application to the Web server, rather than requiring separate connections.</p>

     

       170
       +
       

     

       171
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        typedef struct {

     

       172
       +
                   unsigned char version;

     

       173
       +
                   unsigned char type;

     

       174
       +
                   unsigned char requestIdB1;

     

       175
       +
                   unsigned char requestIdB0;

     

       176
       +
                   unsigned char contentLengthB1;

     

       177
       +
                   unsigned char contentLengthB0;

     

       178
       +
                   unsigned char paddingLength;

     

       179
       +
                   unsigned char reserved;

     

       180
       +
                   unsigned char contentData[contentLength];

     

       181
       +
                   unsigned char paddingData[paddingLength];

     

       182
       +
               } FCGI_Record;

     

       183
       +
       </code></pre></div></div>

     

       184
       +
       

     

       185
       +
       <p>A FastCGI record consists of a fixed-length prefix followed by a variable number of content and padding bytes. A record contains seven components:</p>

     

       186
       +
       

     

       187
       +
       <ul>

     

       188
       +
         <li><tt>version</tt>: Identifies the FastCGI protocol version. This specification documents <tt>FCGI_VERSION_1</tt>.</li>

     

       189
       +
         <li><tt>type</tt>: Identifies the FastCGI record type, i.e. the general function that the record performs. Specific record types and their functions are detailed in later sections.</li>

     

       190
       +
         <li><tt>requestId</tt>: Identifies the <em>FastCGI request</em> to which the record belongs.</li>

     

       191
       +
         <li><tt>contentLength</tt>: The number of bytes in the <tt>contentData</tt> component of the record.</li>

     

       192
       +
         <li><tt>paddingLength</tt>: The number of bytes in the <tt>paddingData</tt> component of the record.</li>

     

       193
       +
         <li><tt>contentData</tt>: Between 0 and 65535 bytes of data, interpreted according to the record type.</li>

     

       194
       +
         <li><tt>paddingData</tt>: Between 0 and 255 bytes of data, which are ignored.</li>

     

       195
       +
       </ul>

     

       196
       +
       

     

       197
       +
       <p>We use a relaxed C <tt>struct</tt> initializer syntax to specify constant FastCGI records. We omit the <tt>version</tt> component, ignore padding, and treat <tt>requestId</tt> as a number. Thus <tt>{FCGI_END_REQUEST, 1, {FCGI_REQUEST_COMPLETE,0}}</tt> is a record with <tt>type == FCGI_END_REQUEST</tt>, <tt>requestId == 1</tt>, and <tt>contentData == {FCGI_REQUEST_COMPLETE,0}</tt>.</p>

     

       198
       +
       

     

       199
       +
       <h5 id="padding">Padding</h5>

     

       200
       +
       

     

       201
       +
       <p>The protocol allows senders to pad the records they send, and requires receivers to interpret the <tt>paddingLength</tt> and skip the <tt>paddingData</tt>. Padding allows senders to keep data aligned for more efficient processing. Experience with the X window system protocols shows the performance benefit of such alignment.</p>

     

       202
       +
       

     

       203
       +
       <p>We recommend that records be placed on boundaries that are multiples of eight bytes. The fixed-length portion of a <tt>FCGI_Record</tt> is eight bytes.</p>

     

       204
       +
       

     

       205
       +
       <h5 id="managing-request-ids">Managing Request IDs</h5>

     

       206
       +
       

     

       207
       +
       <p>The Web server re-uses FastCGI request IDs; the application keeps track of the current state of each request ID on a given transport connection. A request ID <tt>R</tt> becomes active when the application receives a record <tt>{FCGI_BEGIN_REQUEST, R, …}</tt> and becomes inactive when the application sends a record <tt>{FCGI_END_REQUEST, R, …}</tt> to the Web server.</p>

     

       208
       +
       

     

       209
       +
       <p>While a request ID <tt>R</tt> is inactive, the application ignores records with <tt>requestId == R</tt>, except for <tt>FCGI_BEGIN_REQUEST</tt> records as just described.</p>

     

       210
       +
       

     

       211
       +
       <p>The Web server attempts to keep FastCGI request IDs small. That way the application can keep track of request ID states using a short array rather than a long array or a hash table. An application also has the option of accepting only one request at a time. In this case the application simply checks incoming <tt>requestId</tt> values against the current request ID.</p>

     

       212
       +
       

     

       213
       +
       <h5 id="types-of-record-types">Types of Record Types</h5>

     

       214
       +
       

     

       215
       +
       <p>There are two useful ways of classifying FastCGI record types.</p>

     

       216
       +
       

     

       217
       +
       <p>The first distinction is between <em>management</em> records and <em>application</em> records. A management record contains information that is not specific to any Web server request, such as information about the protocol capabilities of the application. An application record contains information about a particular request, identified by the <tt>requestId</tt> component.</p>

     

       218
       +
       

     

       219
       +
       <p>Management records have a <tt>requestId</tt> value of zero, also called the <em>null request ID</em>. Application records have a nonzero <tt>requestId</tt>.</p>

     

       220
       +
       

     

       221
       +
       <p>The second distinction is between <em>discrete</em> and <em>stream</em> records. A discrete record contains a meaningful unit of data all by itself. A stream record is part of a <em>stream</em>, i.e. a series of zero or more non-empty records (<tt>length != 0</tt>) of the stream type, followed by an empty record (<tt>length == 0</tt>) of the stream type. The <tt>contentData</tt> components of a stream’s records, when concatenated, form a byte sequence; this byte sequence is the value of the stream. Therefore the value of a stream is independent of how many records it contains or how its bytes are divided among the non-empty records.</p>

     

       222
       +
       

     

       223
       +
       <p>These two classifications are independent. Among the record types defined in this version of the FastCGI protocol, all management record types are also discrete record types, and nearly all application record types are stream record types. But three application record types are discrete, and nothing prevents defining a management record type that’s a stream in some later version of the protocol.</p>

     

       224
       +
       

     

       225
       +
       <h4 id="34-name-value-pairs"><a name="S3.4">3.4 Name-Value Pairs</a></h4>

     

       226
       +
       

     

       227
       +
       <p>In many of their roles, FastCGI applications need to read and write varying numbers of variable-length values. So it is useful to adopt a standard format for encoding a name-value pair.</p>

     

       228
       +
       

     

       229
       +
       <p>FastCGI transmits a name-value pair as the length of the name, followed by the length of the value, followed by the name, followed by the value. Lengths of 127 bytes and less can be encoded in one byte, while longer lengths are always encoded in four bytes:</p>

     

       230
       +
       

     

       231
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        typedef struct {

     

       232
       +
                   unsigned char nameLengthB0;  /* nameLengthB0  &gt;&gt; 7 == 0 */

     

       233
       +
                   unsigned char valueLengthB0; /* valueLengthB0 &gt;&gt; 7 == 0 */

     

       234
       +
                   unsigned char nameData[nameLength];

     

       235
       +
                   unsigned char valueData[valueLength];

     

       236
       +
               } FCGI_NameValuePair11;

     

       237
       +
       

     

       238
       +
               typedef struct {

     

       239
       +
                   unsigned char nameLengthB0;  /* nameLengthB0  &gt;&gt; 7 == 0 */

     

       240
       +
                   unsigned char valueLengthB3; /* valueLengthB3 &gt;&gt; 7 == 1 */

     

       241
       +
                   unsigned char valueLengthB2;

     

       242
       +
                   unsigned char valueLengthB1;

     

       243
       +
                   unsigned char valueLengthB0;

     

       244
       +
                   unsigned char nameData[nameLength];

     

       245
       +
                   unsigned char valueData[valueLength

     

       246
       +
                           ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];

     

       247
       +
               } FCGI_NameValuePair14;

     

       248
       +
       

     

       249
       +
               typedef struct {

     

       250
       +
                   unsigned char nameLengthB3;  /* nameLengthB3  &gt;&gt; 7 == 1 */

     

       251
       +
                   unsigned char nameLengthB2;

     

       252
       +
                   unsigned char nameLengthB1;

     

       253
       +
                   unsigned char nameLengthB0;

     

       254
       +
                   unsigned char valueLengthB0; /* valueLengthB0 &gt;&gt; 7 == 0 */

     

       255
       +
                   unsigned char nameData[nameLength

     

       256
       +
                           ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];

     

       257
       +
                   unsigned char valueData[valueLength];

     

       258
       +
               } FCGI_NameValuePair41;

     

       259
       +
       

     

       260
       +
               typedef struct {

     

       261
       +
                   unsigned char nameLengthB3;  /* nameLengthB3  &gt;&gt; 7 == 1 */

     

       262
       +
                   unsigned char nameLengthB2;

     

       263
       +
                   unsigned char nameLengthB1;

     

       264
       +
                   unsigned char nameLengthB0;

     

       265
       +
                   unsigned char valueLengthB3; /* valueLengthB3 &gt;&gt; 7 == 1 */

     

       266
       +
                   unsigned char valueLengthB2;

     

       267
       +
                   unsigned char valueLengthB1;

     

       268
       +
                   unsigned char valueLengthB0;

     

       269
       +
                   unsigned char nameData[nameLength

     

       270
       +
                           ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];

     

       271
       +
                   unsigned char valueData[valueLength

     

       272
       +
                           ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];

     

       273
       +
               } FCGI_NameValuePair44;

     

       274
       +
       </code></pre></div></div>

     

       275
       +
       

     

       276
       +
       <p>The high-order bit of the first byte of a length indicates the length’s encoding. A high-order zero implies a one-byte encoding, a one a four-byte encoding.</p>

     

       277
       +
       

     

       278
       +
       <p>This name-value pair format allows the sender to transmit binary values without additional encoding, and enables the receiver to allocate the correct amount of storage immediately even for large values.</p>

     

       279
       +
       

     

       280
       +
       <h4 id="35-closing-transport-connections"><a name="S3.5">3.5 Closing Transport Connections</a></h4>

     

       281
       +
       

     

       282
       +
       <p>The Web server controls the lifetime of transport connections. The Web server can close a connection when no requests are active. Or the Web server can delegate close authority to the application (see <tt>FCGI_BEGIN_REQUEST</tt>). In this case the application closes the connection at the end of a specified request.</p>

     

       283
       +
       

     

       284
       +
       <p>This flexibility accommodates a variety of application styles. Simple applications will process one request at a time and accept a new transport connection for each request. More complex applications will process concurrent requests, over one or multiple transport connections, and will keep transport connections open for long periods of time.</p>

     

       285
       +
       

     

       286
       +
       <p>A simple application gets a significant performance boost by closing the transport connection when it has finished writing its response. The Web server needs to control the connection lifetime for long-lived connections.</p>

     

       287
       +
       

     

       288
       +
       <p>When an application closes a connection or finds that a connection has closed, the application initiates a new connection.</p>

     

       289
       +
       

     

       290
       +
       <h3 id="4-management-record-types"><a name="S4">4. Management Record Types</a></h3>

     

       291
       +
       

     

       292
       +
       <h4 id="41-fcgi_get_values-fcgi_get_values_result"><a name="S4.1">4.1 <tt>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</tt></a></h4>

     

       293
       +
       

     

       294
       +
       <p>The Web server can query specific variables within the application. The server will typically perform a query on application startup in order to to automate certain aspects of system configuration.</p>

     

       295
       +
       

     

       296
       +
       <p>The application receives a query as a record <tt>{FCGI_GET_VALUES, 0, …}</tt>. The <tt>contentData</tt> portion of a <tt>FCGI_GET_VALUES</tt> record contains a sequence of name-value pairs with empty values.</p>

     

       297
       +
       

     

       298
       +
       <p>The application responds by sending a record <tt>{FCGI_GET_VALUES_RESULT, 0, …}</tt> with the values supplied. If the application doesn’t understand a variable name that was included in the query, it omits that name from the response.</p>

     

       299
       +
       

     

       300
       +
       <p><tt>FCGI_GET_VALUES</tt> is designed to allow an open-ended set of variables. The initial set provides information to help the server perform application and connection management:</p>

     

       301
       +
       

     

       302
       +
       <ul>

     

       303
       +
         <li><tt>FCGI_MAX_CONNS</tt>: The maximum number of concurrent transport connections this application will accept, e.g. <tt>“1”</tt> or <tt>“10”</tt>.</li>

     

       304
       +
         <li><tt>FCGI_MAX_REQS</tt>: The maximum number of concurrent requests this application will accept, e.g. <tt>“1”</tt> or <tt>“50”</tt>.</li>

     

       305
       +
         <li><tt>FCGI_MPXS_CONNS</tt>: <tt>“0”</tt> if this application does not multiplex connections (i.e. handle concurrent requests over each connection), <tt>“1”</tt> otherwise.</li>

     

       306
       +
       </ul>

     

       307
       +
       

     

       308
       +
       <p>An application may receive a <tt>FCGI_GET_VALUES</tt> record at any time. The application’s response should not involve the application proper but only the FastCGI library.</p>

     

       309
       +
       

     

       310
       +
       <h4 id="42-fcgi_unknown_type"><a name="S4.2">4.2 <tt>FCGI_UNKNOWN_TYPE</tt></a></h4>

     

       311
       +
       

     

       312
       +
       <p>The set of management record types is likely to grow in future versions of this protocol. To provide for this evolution, the protocol includes the <tt>FCGI_UNKNOWN_TYPE</tt> management record. When an application receives a management record whose type <tt>T</tt> it does not understand, the application responds with <tt>{FCGI_UNKNOWN_TYPE, 0, {T}}</tt>.</p>

     

       313
       +
       

     

       314
       +
       <p>The <tt>contentData</tt> component of a <tt>FCGI_UNKNOWN_TYPE</tt> record has the form:</p>

     

       315
       +
       

     

       316
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        typedef struct {

     

       317
       +
                   unsigned char type;    

     

       318
       +
                   unsigned char reserved[7];

     

       319
       +
               } FCGI_UnknownTypeBody;

     

       320
       +
       </code></pre></div></div>

     

       321
       +
       

     

       322
       +
       <p>The <tt>type</tt> component is the type of the unrecognized management record.</p>

     

       323
       +
       

     

       324
       +
       <h3 id="5-application-record-types"><a name="S5">5. Application Record Types</a></h3>

     

       325
       +
       

     

       326
       +
       <h4 id="51-fcgi_begin_request"><a name="S5.1">5.1 <tt>FCGI_BEGIN_REQUEST</tt></a></h4>

     

       327
       +
       

     

       328
       +
       <p>The Web server sends a <tt>FCGI_BEGIN_REQUEST</tt> record to start a request.</p>

     

       329
       +
       

     

       330
       +
       <p>The <tt>contentData</tt> component of a <tt>FCGI_BEGIN_REQUEST</tt> record has the form:</p>

     

       331
       +
       

     

       332
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        typedef struct {

     

       333
       +
                   unsigned char roleB1;

     

       334
       +
                   unsigned char roleB0;

     

       335
       +
                   unsigned char flags;

     

       336
       +
                   unsigned char reserved[5];

     

       337
       +
               } FCGI_BeginRequestBody;

     

       338
       +
       </code></pre></div></div>

     

       339
       +
       

     

       340
       +
       <p>The <tt>role</tt> component sets the role the Web server expects the application to play. The currently-defined roles are:</p>

     

       341
       +
       

     

       342
       +
       <ul>

     

       343
       +
         <li><tt>FCGI_RESPONDER</tt></li>

     

       344
       +
         <li><tt>FCGI_AUTHORIZER</tt></li>

     

       345
       +
         <li><tt>FCGI_FILTER</tt></li>

     

       346
       +
       </ul>

     

       347
       +
       

     

       348
       +
       <p>Roles are described in more detail in <a href="#S6">Section 6</a> below.</p>

     

       349
       +
       

     

       350
       +
       <p>The <tt>flags</tt> component contains a bit that controls connection shutdown:</p>

     

       351
       +
       

     

       352
       +
       <ul>

     

       353
       +
         <li><tt>flags &amp; FCGI_KEEP_CONN</tt>: If zero, the application closes the connection after responding to this request. If not zero, the application does not close the connection after responding to this request; the Web server retains responsibility for the connection.</li>

     

       354
       +
       </ul>

     

       355
       +
       

     

       356
       +
       <h4 id="52-name-value-pair-stream-fcgi_params"><a name="S5.2">5.2 Name-Value Pair Stream: <tt>FCGI_PARAMS</tt></a></h4>

     

       357
       +
       

     

       358
       +
       <p><tt>FCGI_PARAMS</tt></p>

     

       359
       +
       

     

       360
       +
       <p>is a stream record type used in sending name-value pairs from the Web server to the application. The name-value pairs are sent down the stream one after the other, in no specified order.</p>

     

       361
       +
       

     

       362
       +
       <h4 id="53-byte-streams-fcgi_stdin-fcgi_data-fcgi_stdout-fcgi_stderr"><a name="S5.3">5.3 Byte Streams: <tt>FCGI_STDIN</tt>, <tt>FCGI_DATA</tt>, <tt>FCGI_STDOUT</tt>, <tt>FCGI_STDERR</tt></a></h4>

     

       363
       +
       

     

       364
       +
       <p><tt>FCGI_STDIN</tt></p>

     

       365
       +
       

     

       366
       +
       <p>is a stream record type used in sending arbitrary data from the Web server to the application. <tt>FCGI_DATA</tt> is a second stream record type used to send additional data to the application.</p>

     

       367
       +
       

     

       368
       +
       <p><tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt> are stream record types for sending arbitrary data and error data respectively from the application to the Web server.</p>

     

       369
       +
       

     

       370
       +
       <h4 id="54-fcgi_abort_request"><a name="S5.4">5.4 <tt>FCGI_ABORT_REQUEST</tt></a></h4>

     

       371
       +
       

     

       372
       +
       <p>The Web server sends a <tt>FCGI_ABORT_REQUEST</tt> record to abort a request. After receiving <tt>{FCGI_ABORT_REQUEST, R}</tt>, the application responds as soon as possible with <tt>{FCGI_END_REQUEST, R, {FCGI_REQUEST_COMPLETE, appStatus}}</tt>. This is truly a response from the application, not a low-level acknowledgement from the FastCGI library.</p>

     

       373
       +
       

     

       374
       +
       <p>A Web server aborts a FastCGI request when an HTTP client closes its transport connection while the FastCGI request is running on behalf of that client. The situation may seem unlikely; most FastCGI requests will have short response times, with the Web server providing output buffering if the client is slow. But the FastCGI application may be delayed communicating with another system, or performing a server push.</p>

     

       375
       +
       

     

       376
       +
       <p>When a Web server is not multiplexing requests over a transport connection, the Web server can abort a request by closing the request’s transport connection. But with multiplexed requests, closing the transport connection has the unfortunate effect of aborting <em>all</em> the requests on the connection.</p>

     

       377
       +
       

     

       378
       +
       <h4 id="55-fcgi_end_request"><a name="S5.5">5.5 <tt>FCGI_END_REQUEST</tt></a></h4>

     

       379
       +
       

     

       380
       +
       <p>The application sends a <tt>FCGI_END_REQUEST</tt> record to terminate a request, either because the application has processed the request or because the application has rejected the request.</p>

     

       381
       +
       

     

       382
       +
       <p>The <tt>contentData</tt> component of a <tt>FCGI_END_REQUEST</tt> record has the form:</p>

     

       383
       +
       

     

       384
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>        typedef struct {

     

       385
       +
                   unsigned char appStatusB3;

     

       386
       +
                   unsigned char appStatusB2;

     

       387
       +
                   unsigned char appStatusB1;

     

       388
       +
                   unsigned char appStatusB0;

     

       389
       +
                   unsigned char protocolStatus;

     

       390
       +
                   unsigned char reserved[3];

     

       391
       +
               } FCGI_EndRequestBody;

     

       392
       +
       </code></pre></div></div>

     

       393
       +
       

     

       394
       +
       <p>The <tt>appStatus</tt> component is an application-level status code. Each role documents its usage of <tt>appStatus</tt>.</p>

     

       395
       +
       

     

       396
       +
       <p>The <tt>protocolStatus</tt> component is a protocol-level status code; the possible <tt>protocolStatus</tt> values are:</p>

     

       397
       +
       

     

       398
       +
       <ul>

     

       399
       +
         <li><tt>FCGI_REQUEST_COMPLETE</tt>: normal end of request.</li>

     

       400
       +
         <li><tt>FCGI_CANT_MPX_CONN</tt>: rejecting a new request. This happens when a Web server sends concurrent requests over one connection to an application that is designed to process one request at a time per connection.</li>

     

       401
       +
         <li><tt>FCGI_OVERLOADED</tt>: rejecting a new request. This happens when the application runs out of some resource, e.g. database connections.</li>

     

       402
       +
         <li><tt>FCGI_UNKNOWN_ROLE</tt>: rejecting a new request. This happens when the Web server has specified a role that is unknown to the application.</li>

     

       403
       +
       </ul>

     

       404
       +
       

     

       405
       +
       <h3 id="6-roles"><a name="S6">6. Roles</a></h3>

     

       406
       +
       

     

       407
       +
       <h4 id="61-role-protocols"><a name="S6.1">6.1 Role Protocols</a></h4>

     

       408
       +
       

     

       409
       +
       <p>Role protocols only include records with application record types. They transfer essentially all data using streams.</p>

     

       410
       +
       

     

       411
       +
       <p>To make the protocols reliable and to simplify application programming, role protocols are designed to use <em>nearly sequential marshalling</em>. In a protocol with strictly sequential marshalling, the application receives its first input, then its second, etc. until it has received them all. Similarly, the application sends its first output, then its second, etc. until it has sent them all. Inputs are not interleaved with each other, and outputs are not interleaved with each other.</p>

     

       412
       +
       

     

       413
       +
       <p>The sequential marshalling rule is too restrictive for some FastCGI roles, because CGI programs can write to both <tt>stdout</tt> and <tt>stderr</tt> without timing restrictions. So role protocols that use both <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt> allow these two streams to be interleaved.</p>

     

       414
       +
       

     

       415
       +
       <p>All role protocols use the <tt>FCGI_STDERR</tt> stream just the way <tt>stderr</tt> is used in conventional applications programming: to report application-level errors in an intelligible way. Use of the <tt>FCGI_STDERR</tt> stream is always optional. If an application has no errors to report, it sends either no <tt>FCGI_STDERR</tt> records or one zero-length <tt>FCGI_STDERR</tt> record.</p>

     

       416
       +
       

     

       417
       +
       <p>When a role protocol calls for transmitting a stream other than <tt>FCGI_STDERR</tt>, at least one record of the stream type is always transmitted, even if the stream is empty.</p>

     

       418
       +
       

     

       419
       +
       <p>Again in the interests of reliable protocols and simplified application programming, role protocols are designed to be <em>nearly request-response</em>. In a truly request-response protocol, the application receives all of its input records before sending its first output record. Request-response protocols don’t allow pipelining.</p>

     

       420
       +
       

     

       421
       +
       <p>The request-response rule is too restrictive for some FastCGI roles; after all, CGI programs aren’t restricted to read all of <tt>stdin</tt> before starting to write <tt>stdout</tt>. So some role protocols allow that specific possibility. First the application receives all of its inputs except for a final stream input. As the application begins to receive the final stream input, it can begin writing its output.</p>

     

       422
       +
       

     

       423
       +
       <p>When a role protocol uses <tt>FCGI_PARAMS</tt> to transmit textual values, such as the values that CGI programs obtain from environment variables, the length of the value does not include the terminating null byte, and the value itself does not include a null byte. An application that needs to provide <tt>environ(7)</tt> format name-value pairs must insert an equal sign between the name and value and append a null byte after the value.</p>

     

       424
       +
       

     

       425
       +
       <p>Role protocols do not support the non-parsed header feature of CGI. FastCGI applications set response status using the <tt>Status</tt> and <tt>Location</tt> CGI headers.</p>

     

       426
       +
       

     

       427
       +
       <h4 id="62-responder"><a name="S6.2">6.2 Responder</a></h4>

     

       428
       +
       

     

       429
       +
       <p>A Responder FastCGI application has the same purpose as a CGI/1.1 program: It receives all the information associated with an HTTP request and generates an HTTP response.</p>

     

       430
       +
       

     

       431
       +
       <p>It suffices to explain how each element of CGI/1.1 is emulated by a Responder:</p>

     

       432
       +
       

     

       433
       +
       <ul>

     

       434
       +
         <li>The Responder application receives CGI/1.1 environment variables from the Web server over <tt>FCGI_PARAMS</tt>.</li>

     

       435
       +
         <li>Next the Responder application receives CGI/1.1 <tt>stdin</tt> data from the Web server over <tt>FCGI_STDIN</tt>. The application receives at most <tt>CONTENT_LENGTH</tt> bytes from this stream before receiving the end-of-stream indication. (The application receives less than <tt>CONTENT_LENGTH</tt> bytes only if the HTTP client fails to provide them, e.g. because the client crashed.)</li>

     

       436
       +
         <li>The Responder application sends CGI/1.1 <tt>stdout</tt> data to the Web server over <tt>FCGI_STDOUT</tt>, and CGI/1.1 <tt>stderr</tt> data over <tt>FCGI_STDERR</tt>. The application sends these concurrently, not one after the other. The application must wait to finish reading <tt>FCGI_PARAMS</tt> before it begins writing <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt>, but it needn’t finish reading from <tt>FCGI_STDIN</tt> before it begins writing these two streams.</li>

     

       437
       +
         <li>After sending all its <tt>stdout</tt> and <tt>stderr</tt> data, the Responder application sends a <tt>FCGI_END_REQUEST</tt> record. The application sets the <tt>protocolStatus</tt> component to <tt>FCGI_REQUEST_COMPLETE</tt> and the <tt>appStatus</tt> component to the status code that the CGI program would have returned via the <tt>exit</tt> system call.</li>

     

       438
       +
       </ul>

     

       439
       +
       

     

       440
       +
       <p>A Responder performing an update, e.g. implementing a <tt>POST</tt> method, should compare the number of bytes received on <tt>FCGI_STDIN</tt> with <tt>CONTENT_LENGTH</tt> and abort the update if the two numbers are not equal.</p>

     

       441
       +
       

     

       442
       +
       <h4 id="63-authorizer"><a name="S6.3">6.3 Authorizer</a></h4>

     

       443
       +
       

     

       444
       +
       <p>An Authorizer FastCGI application receives all the information associated with an HTTP request and generates an authorized/unauthorized decision. In case of an authorized decision the Authorizer can also associate name-value pairs with the HTTP request; when giving an unauthorized decision the Authorizer sends a complete response to the HTTP client.</p>

     

       445
       +
       

     

       446
       +
       <p>Since CGI/1.1 defines a perfectly good way to represent the information associated with an HTTP request, Authorizers use the same representation:</p>

     

       447
       +
       

     

       448
       +
       <ul>

     

       449
       +
         <li>The Authorizer application receives HTTP request information from the Web server on the <tt>FCGI_PARAMS</tt> stream, in the same format as a Responder. The Web server does not send <tt>CONTENT_LENGTH</tt>, <tt>PATH_INFO</tt>, <tt>PATH_TRANSLATED</tt>, and <tt>SCRIPT_NAME</tt> headers.</li>

     

       450
       +
         <li>

     

       451
       +
           <p>The Authorizer application sends <tt>stdout</tt> and <tt>stderr</tt> data in the same manner as a Responder. The CGI/1.1 response status specifies the disposition of the request. If the application sends status 200 (OK), the Web server allows access. Depending upon its configuration the Web server may proceed with other access checks, including requests to other Authorizers.</p>

     

       452
       +
       

     

       453
       +
           <p>An Authorizer application’s 200 response may include headers whose names are prefixed with <tt>Variable-</tt>. These headers communicate name-value pairs from the application to the Web server. For instance, the response header</p>

     

       454
       +
       

     

       455
       +
           <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    Variable-AUTH_METHOD: database lookup

     

       456
       +
       </code></pre></div>    </div>

     

       457
       +
       

     

       458
       +
           <p>transmits the value <tt>“database lookup”</tt> with name <tt>AUTH-METHOD</tt>. The server associates such name-value pairs with the HTTP request and includes them in subsequent CGI or FastCGI requests performed in processing the HTTP request. When the application gives a 200 response, the server ignores response headers whose names aren’t prefixed with <tt>Variable-</tt> prefix, and ignores any response content.</p>

     

       459
       +
       

     

       460
       +
           <p>For Authorizer response status values other than “200” (OK), the Web server denies access and sends the response status, headers, and content back to the HTTP client.</p>

     

       461
       +
         </li>

     

       462
       +
       </ul>

     

       463
       +
       

     

       464
       +
       <h4 id="64-filter"><a name="S6.4">6.4 Filter</a></h4>

     

       465
       +
       

     

       466
       +
       <p>A Filter FastCGI application receives all the information associated with an HTTP request, plus an extra stream of data from a file stored on the Web server, and generates a “filtered” version of the data stream as an HTTP response.</p>

     

       467
       +
       

     

       468
       +
       <p>A Filter is similar in functionality to a Responder that takes a data file as a parameter. The difference is that with a Filter, both the data file and the Filter itself can be access controlled using the Web server’s access control mechanisms, while a Responder that takes the name of a data file as a parameter must perform its own access control checks on the data file.</p>

     

       469
       +
       

     

       470
       +
       <p>The steps taken by a Filter are similar to those of a Responder. The server presents the Filter with environment variables first, then standard input (normally form <tt>POST</tt> data), finally the data file input:</p>

     

       471
       +
       

     

       472
       +
       <ul>

     

       473
       +
         <li>Like a Responder, the Filter application receives name-value pairs from the Web server over <tt>FCGI_PARAMS</tt>. Filter applications receive two Filter-specific variables: <tt>FCGI_DATA_LAST_MOD</tt> and <tt>FCGI_DATA_LENGTH</tt>.</li>

     

       474
       +
         <li>Next the Filter application receives CGI/1.1 <tt>stdin</tt> data from the Web server over <tt>FCGI_STDIN</tt>. The application receives at most <tt>CONTENT_LENGTH</tt> bytes from this stream before receiving the end-of-stream indication. (The application receives less than <tt>CONTENT_LENGTH</tt> bytes only if the HTTP client fails to provide them, e.g. because the client crashed.)</li>

     

       475
       +
         <li>Next the Filter application receives the file data from the Web server over <tt>FCGI_DATA</tt>. This file’s last modification time (expressed as an integer number of seconds since the epoch January 1, 1970 UTC) is <tt>FCGI_DATA_LAST_MOD</tt>; the application may consult this variable and respond from a cache without reading the file data. The application reads at most <tt>FCGI_DATA_LENGTH</tt> bytes from this stream before receiving the end-of-stream indication.</li>

     

       476
       +
         <li>The Filter application sends CGI/1.1 <tt>stdout</tt> data to the Web server over <tt>FCGI_STDOUT</tt>, and CGI/1.1 <tt>stderr</tt> data over <tt>FCGI_STDERR</tt>. The application sends these concurrently, not one after the other. The application must wait to finish reading <tt>FCGI_STDIN</tt> before it begins writing <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt>, but it needn’t finish reading from <tt>FCGI_DATA</tt> before it begins writing these two streams.</li>

     

       477
       +
         <li>After sending all its <tt>stdout</tt> and <tt>stderr</tt> data, the application sends a <tt>FCGI_END_REQUEST</tt> record. The application sets the <tt>protocolStatus</tt> component to <tt>FCGI_REQUEST_COMPLETE</tt> and the <tt>appStatus</tt> component to the status code that a similar CGI program would have returned via the <tt>exit</tt> system call.</li>

     

       478
       +
       </ul>

     

       479
       +
       

     

       480
       +
       <p>A Filter should compare the number of bytes received on <tt>FCGI_STDIN</tt> with <tt>CONTENT_LENGTH</tt> and on <tt>FCGI_DATA</tt> with <tt>FCGI_DATA_LENGTH</tt>. If the numbers don’t match and the Filter is a query, the Filter response should provide an indication that data is missing. If the numbers don’t match and the Filter is an update, the Filter should abort the update.</p>

     

       481
       +
       

     

       482
       +
       <h3 id="7-errors"><a name="S7">7. Errors</a></h3>

     

       483
       +
       

     

       484
       +
       <p>A FastCGI application exits with zero status to indicate that it terminated on purpose, e.g. in order to perform a crude form of garbage collection. A FastCGI application that exits with nonzero status is assumed to have crashed. How a Web server or other application manager responds to applications that exit with zero or nonzero status is outside the scope of this specification.</p>

     

       485
       +
       

     

       486
       +
       <p>A Web server can request that a FastCGI application exit by sending it <tt>SIGTERM</tt>. If the application ignores <tt>SIGTERM</tt> the Web server can resort to <tt>SIGKILL</tt>.</p>

     

       487
       +
       

     

       488
       +
       <p>FastCGI applications report application-level errors with the <tt>FCGI_STDERR</tt> stream and the <tt>appStatus</tt> component of the <tt>FCGI_END_REQUEST</tt> record. In many cases an error will be reported directly to the user via the <tt>FCGI_STDOUT</tt> stream.</p>

     

       489
       +
       

     

       490
       +
       <p>On Unix, applications report lower-level errors, including FastCGI protocol errors and syntax errors in FastCGI environment variables, to <tt>syslog</tt>. Depending upon the severity of the error, the application may either continue or exit with nonzero status.</p>

     

       491
       +
       

     

       492
       +
       <h3 id="8-types-and-constants"><a name="S8">8. Types and Constants</a></h3>

     

       493
       +
       

     

       494
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/*

     

       495
       +
        * Listening socket file number

     

       496
       +
        */

     

       497
       +
       #define FCGI_LISTENSOCK_FILENO 0

     

       498
       +
       

     

       499
       +
       typedef struct {

     

       500
       +
           unsigned char version;

     

       501
       +
           unsigned char type;

     

       502
       +
           unsigned char requestIdB1;

     

       503
       +
           unsigned char requestIdB0;

     

       504
       +
           unsigned char contentLengthB1;

     

       505
       +
           unsigned char contentLengthB0;

     

       506
       +
           unsigned char paddingLength;

     

       507
       +
           unsigned char reserved;

     

       508
       +
       } FCGI_Header;

     

       509
       +
       

     

       510
       +
       /*

     

       511
       +
        * Number of bytes in a FCGI_Header.  Future versions of the protocol

     

       512
       +
        * will not reduce this number.

     

       513
       +
        */

     

       514
       +
       #define FCGI_HEADER_LEN  8

     

       515
       +
       

     

       516
       +
       /*

     

       517
       +
        * Value for version component of FCGI_Header

     

       518
       +
        */

     

       519
       +
       #define FCGI_VERSION_1           1

     

       520
       +
       

     

       521
       +
       /*

     

       522
       +
        * Values for type component of FCGI_Header

     

       523
       +
        */

     

       524
       +
       #define FCGI_BEGIN_REQUEST       1

     

       525
       +
       #define FCGI_ABORT_REQUEST       2

     

       526
       +
       #define FCGI_END_REQUEST         3

     

       527
       +
       #define FCGI_PARAMS              4

     

       528
       +
       #define FCGI_STDIN               5

     

       529
       +
       #define FCGI_STDOUT              6

     

       530
       +
       #define FCGI_STDERR              7

     

       531
       +
       #define FCGI_DATA                8

     

       532
       +
       #define FCGI_GET_VALUES          9

     

       533
       +
       #define FCGI_GET_VALUES_RESULT  10

     

       534
       +
       #define FCGI_UNKNOWN_TYPE       11

     

       535
       +
       #define FCGI_MAXTYPE (FCGI_UNKNOWN_TYPE)

     

       536
       +
       

     

       537
       +
       /*

     

       538
       +
        * Value for requestId component of FCGI_Header

     

       539
       +
        */

     

       540
       +
       #define FCGI_NULL_REQUEST_ID     0

     

       541
       +
       

     

       542
       +
       typedef struct {

     

       543
       +
           unsigned char roleB1;

     

       544
       +
           unsigned char roleB0;

     

       545
       +
           unsigned char flags;

     

       546
       +
           unsigned char reserved[5];

     

       547
       +
       } FCGI_BeginRequestBody;

     

       548
       +
       

     

       549
       +
       typedef struct {

     

       550
       +
           FCGI_Header header;

     

       551
       +
           FCGI_BeginRequestBody body;

     

       552
       +
       } FCGI_BeginRequestRecord;

     

       553
       +
       

     

       554
       +
       /*

     

       555
       +
        * Mask for flags component of FCGI_BeginRequestBody

     

       556
       +
        */

     

       557
       +
       #define FCGI_KEEP_CONN  1

     

       558
       +
       

     

       559
       +
       /*

     

       560
       +
        * Values for role component of FCGI_BeginRequestBody

     

       561
       +
        */

     

       562
       +
       #define FCGI_RESPONDER  1

     

       563
       +
       #define FCGI_AUTHORIZER 2

     

       564
       +
       #define FCGI_FILTER     3

     

       565
       +
       

     

       566
       +
       typedef struct {

     

       567
       +
           unsigned char appStatusB3;

     

       568
       +
           unsigned char appStatusB2;

     

       569
       +
           unsigned char appStatusB1;

     

       570
       +
           unsigned char appStatusB0;

     

       571
       +
           unsigned char protocolStatus;

     

       572
       +
           unsigned char reserved[3];

     

       573
       +
       } FCGI_EndRequestBody;

     

       574
       +
       

     

       575
       +
       typedef struct {

     

       576
       +
           FCGI_Header header;

     

       577
       +
           FCGI_EndRequestBody body;

     

       578
       +
       } FCGI_EndRequestRecord;

     

       579
       +
       

     

       580
       +
       /*

     

       581
       +
        * Values for protocolStatus component of FCGI_EndRequestBody

     

       582
       +
        */

     

       583
       +
       #define FCGI_REQUEST_COMPLETE 0

     

       584
       +
       #define FCGI_CANT_MPX_CONN    1

     

       585
       +
       #define FCGI_OVERLOADED       2

     

       586
       +
       #define FCGI_UNKNOWN_ROLE     3

     

       587
       +
       

     

       588
       +
       /*

     

       589
       +
        * Variable names for FCGI_GET_VALUES / FCGI_GET_VALUES_RESULT records

     

       590
       +
        */

     

       591
       +
       #define FCGI_MAX_CONNS  "FCGI_MAX_CONNS"

     

       592
       +
       #define FCGI_MAX_REQS   "FCGI_MAX_REQS"

     

       593
       +
       #define FCGI_MPXS_CONNS "FCGI_MPXS_CONNS"

     

       594
       +
       

     

       595
       +
       typedef struct {

     

       596
       +
           unsigned char type;    

     

       597
       +
           unsigned char reserved[7];

     

       598
       +
       } FCGI_UnknownTypeBody;

     

       599
       +
       

     

       600
       +
       typedef struct {

     

       601
       +
           FCGI_Header header;

     

       602
       +
           FCGI_UnknownTypeBody body;

     

       603
       +
       } FCGI_UnknownTypeRecord;

     

       604
       +
       </code></pre></div></div>

     

       605
       +
       

     

       606
       +
       <h3 id="9-references"><a name="S9">9. References</a></h3>

     

       607
       +
       

     

       608
       +
       <p><a href="https://www.w3.org/CGI/">The WWW Common Gateway Interface at W3C</a></p>

     

       609
       +
       

     

       610
       +
       <h3 id="a-table-properties-of-the-record-types"><a name="SA">A. Table: Properties of the record types</a></h3>

     

       611
       +
       

     

       612
       +
       <p>The following chart lists all of the record types and indicates these properties of each:</p>

     

       613
       +
       

     

       614
       +
       <ul>

     

       615
       +
         <li><tt>WS-&gt;App</tt>: records of this type can only be sent by the Web server to the application. Records of other types can only be sent by the application to the Web server.</li>

     

       616
       +
         <li><tt>management</tt>: records of this type contain information that is not specific to a Web server request, and use the null request ID. Records of other types contain request-specific information, and cannot use the null request ID.</li>

     

       617
       +
         <li><tt>stream</tt>: records of this type form a stream, terminated by a record with empty <tt>contentData</tt>. Records of other types are discrete; each carries a meaningful unit of data.</li>

     

       618
       +
       </ul>

     

       619
       +
       

     

       620
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>                               WS-&gt;App   management  stream

     

       621
       +
       

     

       622
       +
               FCGI_GET_VALUES           x          x

     

       623
       +
               FCGI_GET_VALUES_RESULT               x

     

       624
       +
               FCGI_UNKNOWN_TYPE                    x

     

       625
       +
       

     

       626
       +
               FCGI_BEGIN_REQUEST        x

     

       627
       +
               FCGI_ABORT_REQUEST        x

     

       628
       +
               FCGI_END_REQUEST

     

       629
       +
               FCGI_PARAMS               x                    x

     

       630
       +
               FCGI_STDIN                x                    x

     

       631
       +
               FCGI_DATA                 x                    x

     

       632
       +
               FCGI_STDOUT                                    x 

     

       633
       +
               FCGI_STDERR                                    x     

     

       634
       +
       

     

       635
       +
       </code></pre></div></div>

     

       636
       +
       

     

       637
       +
       <h3 id="b-typical-protocol-message-flow"><a name="SB">B. Typical Protocol Message Flow</a></h3>

     

       638
       +
       

     

       639
       +
       <p>Additional notational conventions for the examples:</p>

     

       640
       +
       

     

       641
       +
       <ul>

     

       642
       +
         <li>The <tt>contentData</tt> of stream records (<tt>FCGI_PARAMS</tt>, <tt>FCGI_STDIN</tt>, <tt>FCGI_STDOUT</tt>, and <tt>FCGI_STDERR</tt>) is represented as a character string. A string ending in <tt>” … “</tt> is too long to display, so only a prefix is shown.</li>

     

       643
       +
         <li>Messages sent to the Web server are indented with respect to messages received from the Web server.</li>

     

       644
       +
         <li>Messages are shown in the time sequence experienced by the application.</li>

     

       645
       +
       </ul>

     

       646
       +
       

     

       647
       +
       <p>1. A simple request with no data on <tt>stdin</tt>, and a successful response:</p>

     

       648
       +
       

     

       649
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}

     

       650
       +
       {FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}

     

       651
       +
       {FCGI_PARAMS,          1, ""}

     

       652
       +
       {FCGI_STDIN,           1, ""}

     

       653
       +
       

     

       654
       +
           {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... "}

     

       655
       +
           {FCGI_STDOUT,      1, ""}

     

       656
       +
           {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}

     

       657
       +
       </code></pre></div></div>

     

       658
       +
       

     

       659
       +
       <p>2. Similar to example 1, but this time with data on <tt>stdin</tt>. The Web server chooses to send the parameters using more <tt>FCGI_PARAMS</tt> records than before:</p>

     

       660
       +
       

     

       661
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}

     

       662
       +
       {FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SER"}

     

       663
       +
       {FCGI_PARAMS,          1, "VER_ADDR199.170.183.42 ... "}

     

       664
       +
       {FCGI_PARAMS,          1, ""}

     

       665
       +
       {FCGI_STDIN,           1, "quantity=100&amp;item=3047936"}

     

       666
       +
       {FCGI_STDIN,           1, ""}

     

       667
       +
       

     

       668
       +
           {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... "}

     

       669
       +
           {FCGI_STDOUT,      1, ""}

     

       670
       +
           {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}

     

       671
       +
       </code></pre></div></div>

     

       672
       +
       

     

       673
       +
       <p>3. Similar to example 1, but this time the application detects an error. The application logs a message to <tt>stderr</tt>, returns a page to the client, and returns non-zero exit status to the Web server. The application chooses to send the page using more <tt>FCGI_STDOUT</tt> records:</p>

     

       674
       +
       

     

       675
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}

     

       676
       +
       {FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}

     

       677
       +
       {FCGI_PARAMS,          1, ""}

     

       678
       +
       {FCGI_STDIN,           1, ""}

     

       679
       +
       

     

       680
       +
           {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n&lt;ht"}

     

       681
       +
           {FCGI_STDERR,      1, "config error: missing SI_UID\n"}

     

       682
       +
           {FCGI_STDOUT,      1, "ml&gt;\n&lt;head&gt; ... "}

     

       683
       +
           {FCGI_STDOUT,      1, ""}

     

       684
       +
           {FCGI_STDERR,      1, ""}

     

       685
       +
           {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}}

     

       686
       +
       </code></pre></div></div>

     

       687
       +
       

     

       688
       +
       <p>4. Two instances of example 1, multiplexed onto a single connection. The first request is more difficult than the second, so the application finishes the requests out of order:</p>

     

       689
       +
       

     

       690
       +
       <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, FCGI_KEEP_CONN}}

     

       691
       +
       {FCGI_PARAMS,          1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}

     

       692
       +
       {FCGI_PARAMS,          1, ""}

     

       693
       +
       {FCGI_BEGIN_REQUEST,   2, {FCGI_RESPONDER, FCGI_KEEP_CONN}}

     

       694
       +
       {FCGI_PARAMS,          2, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}

     

       695
       +
       {FCGI_STDIN,           1, ""}

     

       696
       +
       

     

       697
       +
           {FCGI_STDOUT,      1, "Content-type: text/html\r\n\r\n"}

     

       698
       +
       

     

       699
       +
       {FCGI_PARAMS,          2, ""}

     

       700
       +
       {FCGI_STDIN,           2, ""}

     

       701
       +
       

     

       702
       +
           {FCGI_STDOUT,      2, "Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... "}

     

       703
       +
           {FCGI_STDOUT,      2, ""}

     

       704
       +
           {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}}

     

       705
       +
           {FCGI_STDOUT,      1, "&lt;html&gt;\n&lt;head&gt; ... "}

     

       706
       +
           {FCGI_STDOUT,      1, ""}

     

       707
       +
           {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}

     

       708
       +
       </code></pre></div></div>

     

       709
       +
       

     

       710
       +
       <hr />

     

       711
       +
       

     

       712
       +
       <p><strong>© 1995, 1996 Open Market, Inc. / <a href="https://www.linkedin.com/in/mark-brown-32a01b11/">Mark R. Brown</a></strong></p>

     

       713
       +
       

     

       714
       +
       

     

       715
       +
             <footer class="site-footer">

     

       716
       +
               

     

       717
       +
                  <span class="site-footer-owner"><a href="https://github.com/FastCGI-Archives">FastCGI Github Archives</a> is maintained by <a href="https://github.com/mcarbonneaux">mcarbonneaux</a>.</span>

     

       718
       +
                       

     

       719
       +
             </footer>

     

       720
       +
           </section>

     

       721
       +
       

     

       722
       +
           

     

       723
       +
             <!-- Google tag (gtag.js) -->

     

       724
       +
             <script async src="https://www.googletagmanager.com/gtag/js?id=G-Y204H06GVK"></script>

     

       725
       +
             <script>

     

       726
       +
               window.dataLayer = window.dataLayer || [];

     

       727
       +
               function gtag(){dataLayer.push(arguments);}

     

       728
       +
               gtag('js', new Date());

     

       729
       +
       

     

       730
       +
               gtag('config', 'G-Y204H06GVK');

     

       731
       +
             </script>

     

       732
       +
       

     

       733
       +
           

     

       734
       +
         </body>

     

       735
       +
       </html>

+1905

spec/OCaml-EIO-README.md

···

       1
       +
       [API reference][Eio API] | [#eio Matrix chat](https://matrix.to/#/#eio:roscidus.com) | [Dev meetings][]

     

       2
       +
       

     

       3
       +
       # Eio &mdash; Effects-Based Parallel IO for OCaml

     

       4
       +
       

     

       5
       +
       Eio provides an effects-based direct-style IO stack for OCaml 5.

     

       6
       +
       For example, you can use Eio to read and write files, make network connections,

     

       7
       +
       or perform CPU-intensive calculations, running multiple operations at the same time.

     

       8
       +
       It aims to be easy to use, secure, well documented, and fast.

     

       9
       +
       A generic cross-platform API is implemented by optimised backends for different platforms.

     

       10
       +
       Eio replaces existing concurrency libraries such as Lwt

     

       11
       +
       (Eio and Lwt libraries can also be used together).

     

       12
       +
       

     

       13
       +
       ## Contents

     

       14
       +
       

     

       15
       +
       <!-- vim-markdown-toc GFM -->

     

       16
       +
       

     

       17
       +
       * [Motivation](#motivation)

     

       18
       +
       * [Eio packages](#eio-packages)

     

       19
       +
       * [Getting OCaml](#getting-ocaml)

     

       20
       +
       * [Getting Eio](#getting-eio)

     

       21
       +
       * [Running Eio](#running-eio)

     

       22
       +
       * [Testing with Mocks](#testing-with-mocks)

     

       23
       +
       * [Fibers](#fibers)

     

       24
       +
       * [Tracing](#tracing)

     

       25
       +
       * [Cancellation](#cancellation)

     

       26
       +
       * [Racing](#racing)

     

       27
       +
       * [Switches](#switches)

     

       28
       +
       * [Networking](#networking)

     

       29
       +
       * [Design Note: Capabilities](#design-note-capabilities)

     

       30
       +
       * [Buffered Reading and Parsing](#buffered-reading-and-parsing)

     

       31
       +
       * [Buffered Writing](#buffered-writing)

     

       32
       +
       * [Error Handling](#error-handling)

     

       33
       +
       * [Filesystem Access](#filesystem-access)

     

       34
       +
       * [Running processes](#running-processes)

     

       35
       +
       * [Time](#time)

     

       36
       +
       * [Multicore Support](#multicore-support)

     

       37
       +
           * [Domain Manager](#domain-manager)

     

       38
       +
           * [Executor Pool](#executor-pool)

     

       39
       +
       * [Synchronisation Tools](#synchronisation-tools)

     

       40
       +
           * [Promises](#promises)

     

       41
       +
           * [Example: Concurrent Cache](#example-concurrent-cache)

     

       42
       +
           * [Streams](#streams)

     

       43
       +
           * [Example: Worker Pool](#example-worker-pool)

     

       44
       +
           * [Mutexes and Semaphores](#mutexes-and-semaphores)

     

       45
       +
           * [Conditions](#conditions)

     

       46
       +
           * [Example: Signal handlers](#example-signal-handlers)

     

       47
       +
       * [Design Note: Determinism](#design-note-determinism)

     

       48
       +
       * [Provider Interfaces](#provider-interfaces)

     

       49
       +
       * [Example Applications](#example-applications)

     

       50
       +
       * [Integrations](#integrations)

     

       51
       +
           * [Async](#async)

     

       52
       +
           * [Lwt](#lwt)

     

       53
       +
           * [Unix and System Threads](#unix-and-system-threads)

     

       54
       +
           * [Domainslib](#domainslib)

     

       55
       +
           * [kcas](#kcas)

     

       56
       +
       * [Best Practices](#best-practices)

     

       57
       +
           * [Switches](#switches-1)

     

       58
       +
           * [Casting](#casting)

     

       59
       +
           * [Passing env](#passing-env)

     

       60
       +
       * [Further Reading](#further-reading)

     

       61
       +
       

     

       62
       +
       <!-- vim-markdown-toc -->

     

       63
       +
       

     

       64
       +
       ## Motivation

     

       65
       +
       

     

       66
       +
       The `Unix` library provided with OCaml uses blocking IO operations, and is not well suited to concurrent programs such as network services or interactive applications.

     

       67
       +
       For many years, the solution was to use libraries such as Lwt and Async, which provide a monadic interface.

     

       68
       +
       These libraries allow writing code as if there were multiple threads of execution, each with their own stack, but the stacks are simulated using the heap.

     

       69
       +
       

     

       70
       +
       OCaml 5 added support for "effects", removing the need for monadic code here.

     

       71
       +
       Using effects brings several advantages:

     

       72
       +
       

     

       73
       +
       1. It's faster, because no heap allocations are needed to simulate a stack.

     

       74
       +
       2. Concurrent code can be written in the same style as plain non-concurrent code.

     

       75
       +
       3. Because a real stack is used, backtraces from exceptions work as expected.

     

       76
       +
       4. Other features of the language (such as `try ... with ...`) can be used in concurrent code.

     

       77
       +
       

     

       78
       +
       Additionally, modern operating systems provide high-performance alternatives to the old Unix `select` call.

     

       79
       +
       For example, Linux's io_uring system has applications write the operations they want to perform to a ring buffer,

     

       80
       +
       which Linux handles asynchronously, and Eio can take advantage of this.

     

       81
       +
       

     

       82
       +
       You can always [fall back to using Lwt libraries](#lwt) to provide missing features if necessary.

     

       83
       +
       See [Awesome Multicore OCaml][] for links to other projects using Eio.

     

       84
       +
       

     

       85
       +
       ## Eio packages

     

       86
       +
       

     

       87
       +
       - [Eio][] provides concurrency primitives (promises, etc.) and a high-level, cross-platform OS API.

     

       88
       +
       - [Eio_posix][] provides a cross-platform backend for these APIs for POSIX-type systems.

     

       89
       +
       - [Eio_linux][] provides a Linux io_uring backend for these APIs.

     

       90
       +
       - [Eio_windows][] is for use on Windows (incomplete - [help wanted](https://github.com/ocaml-multicore/eio/issues/125)).

     

       91
       +
       - [Eio_main][] selects an appropriate backend (e.g. `eio_linux` or `eio_posix`), depending on your platform.

     

       92
       +
       - [Eio_js][] allows Eio code to run in the browser, using `js_of_ocaml`.

     

       93
       +
       

     

       94
       +
       ## Getting OCaml

     

       95
       +
       

     

       96
       +
       You'll need OCaml 5.1.0 or later.

     

       97
       +
       You can either install it yourself or build the included [Dockerfile](./Dockerfile).

     

       98
       +
       

     

       99
       +
       To install it yourself:

     

       100
       +
       

     

       101
       +
       1. Make sure you have opam 2.1 or later (run `opam --version` to check).

     

       102
       +
       

     

       103
       +
       2. Use opam to install OCaml:

     

       104
       +
       

     

       105
       +
          ```

     

       106
       +
          opam switch create 5.2.0

     

       107
       +
          ```

     

       108
       +
       

     

       109
       +
       ## Getting Eio

     

       110
       +
       

     

       111
       +
       Install `eio_main` (and `utop` if you want to try it interactively):

     

       112
       +
       

     

       113
       +
       ```

     

       114
       +
       opam install eio_main utop

     

       115
       +
       ```

     

       116
       +
       

     

       117
       +
       If you want to install the latest unreleased development version of Eio, see [HACKING.md](./HACKING.md).

     

       118
       +
       

     

       119
       +
       ## Running Eio

     

       120
       +
       

     

       121
       +
       Try out the examples interactively by running `utop` in the shell.

     

       122
       +
       

     

       123
       +
       First `require` the `eio_main` library. It's also convenient to open the [Eio.Std][]

     

       124
       +
       module, as follows. (The leftmost `#` shown below is the Utop prompt, so enter the text after the

     

       125
       +
       prompt and return after each line.)

     

       126
       +
       

     

       127
       +
       ```ocaml

     

       128
       +
       # #require "eio_main";;

     

       129
       +
       # open Eio.Std;;

     

       130
       +
       ```

     

       131
       +
       

     

       132
       +
       This function writes a greeting to `out` using [Eio.Flow][]:

     

       133
       +
       

     

       134
       +
       ```ocaml

     

       135
       +
       let main out =

     

       136
       +
         Eio.Flow.copy_string "Hello, world!\n" out

     

       137
       +
       ```

     

       138
       +
       

     

       139
       +
       We use [Eio_main.run][] to run the event loop and call `main` from there:

     

       140
       +
       

     

       141
       +
       ```ocaml

     

       142
       +
       # Eio_main.run @@ fun env ->

     

       143
       +
         main (Eio.Stdenv.stdout env);;

     

       144
       +
       Hello, world!

     

       145
       +
       - : unit = ()

     

       146
       +
       ```

     

       147
       +
       

     

       148
       +
       Note that:

     

       149
       +
       

     

       150
       +
       - The `env` argument represents the standard environment of a Unix process, allowing it to interact with the outside world.

     

       151
       +
         A program will typically start by extracting from `env` whatever things the program will need and then calling `main` with them.

     

       152
       +
       

     

       153
       +
       - The type of the `main` function here tells us that this program only interacts via the `out` flow.

     

       154
       +
       

     

       155
       +
       - `Eio_main.run` automatically calls the appropriate run function for your platform.

     

       156
       +
         For example, on Linux this will call `Eio_linux.run`. For non-portable code you can use the platform-specific library directly.

     

       157
       +
       

     

       158
       +
       This example can also be built using dune; see [examples/hello](./examples/hello/).

     

       159
       +
       

     

       160
       +
       ## Testing with Mocks

     

       161
       +
       

     

       162
       +
       Because external resources are provided to `main` as arguments, we can easily replace them with mocks for testing.

     

       163
       +
       For example, instead of giving `main` the real standard output, we can have it write to a buffer:

     

       164
       +
       

     

       165
       +
       ```ocaml

     

       166
       +
       # Eio_main.run @@ fun _env ->

     

       167
       +
         let buffer = Buffer.create 20 in

     

       168
       +
         main (Eio.Flow.buffer_sink buffer);

     

       169
       +
         traceln "Main would print %S" (Buffer.contents buffer);;

     

       170
       +
       +Main would print "Hello, world!\n"

     

       171
       +
       - : unit = ()

     

       172
       +
       ```

     

       173
       +
       

     

       174
       +
       [Eio.traceln][] provides convenient printf-style debugging, without requiring you to plumb `stderr` through your code.

     

       175
       +
       It uses the `Format` module, so you can use the extended formatting directives here too.

     

       176
       +
       

     

       177
       +
       The [Eio_mock][] library provides some convenient pre-built mocks:

     

       178
       +
       

     

       179
       +
       ```ocaml

     

       180
       +
       # #require "eio.mock";;

     

       181
       +
       # Eio_main.run @@ fun _env ->

     

       182
       +
         main (Eio_mock.Flow.make "mock-stdout");;

     

       183
       +
       +mock-stdout: wrote "Hello, world!\n"

     

       184
       +
       - : unit = ()

     

       185
       +
       ```

     

       186
       +
       

     

       187
       +
       ## Fibers

     

       188
       +
       

     

       189
       +
       Here's an example running two threads of execution concurrently using [Eio.Fiber][]:

     

       190
       +
       

     

       191
       +
       ```ocaml

     

       192
       +
       let main _env =

     

       193
       +
         Fiber.both

     

       194
       +
           (fun () -> for x = 1 to 3 do traceln "x = %d" x; Fiber.yield () done)

     

       195
       +
           (fun () -> for y = 1 to 3 do traceln "y = %d" y; Fiber.yield () done);;

     

       196
       +
       ```

     

       197
       +
       

     

       198
       +
       ```ocaml

     

       199
       +
       # Eio_main.run main;;

     

       200
       +
       +x = 1

     

       201
       +
       +y = 1

     

       202
       +
       +x = 2

     

       203
       +
       +y = 2

     

       204
       +
       +x = 3

     

       205
       +
       +y = 3

     

       206
       +
       - : unit = ()

     

       207
       +
       ```

     

       208
       +
       

     

       209
       +
       The two fibers run on a single core, so only one can be running at a time.

     

       210
       +
       Calling an operation that performs an effect (such as `yield`) can switch to a different thread.

     

       211
       +
       

     

       212
       +
       ## Tracing

     

       213
       +
       

     

       214
       +
       When OCaml's tracing is turned on, Eio writes events about many actions,

     

       215
       +
       such as creating fibers or resolving promises.

     

       216
       +
       

     

       217
       +
       You can use [eio-trace][] to capture a trace and display it in a window.

     

       218
       +
       For example, this is a trace of the counting example above:

     

       219
       +
       

     

       220
       +
       ```

     

       221
       +
       dune build ./examples

     

       222
       +
       eio-trace run -- ./_build/default/examples/both/main.exe

     

       223
       +
       ```

     

       224
       +
       

     

       225
       +
       <p align='center'>

     

       226
       +
         <img src="./doc/traces/both-posix.svg"/>

     

       227
       +
       </p>

     

       228
       +
       

     

       229
       +
       The upper horizontal bar is the initial fiber, and the brackets show `Fiber.both` creating a second fiber.

     

       230
       +
       The green segments show when each fiber is running.

     

       231
       +
       Note that the output from `traceln` appears in the trace as well as on the console.

     

       232
       +
       In the eio-trace window, scrolling with the mouse or touchpad will zoom in or out of the diagram.

     

       233
       +
       

     

       234
       +
       Third-party tools, such as [Olly][], can also consume this data.

     

       235
       +
       [examples/trace](./examples/trace/) shows how to consume the events manually.

     

       236
       +
       

     

       237
       +
       ## Cancellation

     

       238
       +
       

     

       239
       +
       Every fiber has a [cancellation context][Eio.Cancel].

     

       240
       +
       If one of the `Fiber.both` fibers fails, the other is cancelled:

     

       241
       +
       

     

       242
       +
       ```ocaml

     

       243
       +
       # Eio_main.run @@ fun _env ->

     

       244
       +
         Fiber.both

     

       245
       +
           (fun () -> for x = 1 to 3 do traceln "x = %d" x; Fiber.yield () done)

     

       246
       +
           (fun () -> failwith "Simulated error");;

     

       247
       +
       +x = 1

     

       248
       +
       Exception: Failure "Simulated error".

     

       249
       +
       ```

     

       250
       +
       

     

       251
       +
       <p align='center'>

     

       252
       +
         <img src="./doc/traces/cancel-posix.svg"/>

     

       253
       +
       </p>

     

       254
       +
       

     

       255
       +
       What happened here was:

     

       256
       +
       

     

       257
       +
       1. `Fiber.both` created a new cancellation context for the child fibers.

     

       258
       +
       2. The first fiber (the lower one in the diagram) ran, printed `x = 1` and yielded.

     

       259
       +
       3. The second fiber raised an exception.

     

       260
       +
       4. `Fiber.both` caught the exception and cancelled the context.

     

       261
       +
       5. The first thread's `yield` raised a `Cancelled` exception there.

     

       262
       +
       6. Once both threads had finished, `Fiber.both` re-raised the original exception.

     

       263
       +
       

     

       264
       +
       There is a tree of cancellation contexts for each domain, and every fiber is in one context.

     

       265
       +
       When an exception is raised, it propagates towards the root until handled, cancelling the other branches as it goes.

     

       266
       +
       You should assume that any operation that can switch fibers can also raise a `Cancelled` exception if an uncaught exception

     

       267
       +
       reaches one of its ancestor cancellation contexts.

     

       268
       +
       

     

       269
       +
       If you want to make an operation non-cancellable, wrap it with `Cancel.protect`

     

       270
       +
       (this creates a new context that isn't cancelled with its parent).

     

       271
       +
       

     

       272
       +
       ## Racing

     

       273
       +
       

     

       274
       +
       `Fiber.first` returns the result of the first fiber to finish, cancelling the other one:

     

       275
       +
       

     

       276
       +
       ```ocaml

     

       277
       +
       # Eio_main.run @@ fun _env ->

     

       278
       +
         let x =

     

       279
       +
           Fiber.first

     

       280
       +
             (fun () ->

     

       281
       +
               traceln "first fiber delayed...";

     

       282
       +
               Fiber.yield ();

     

       283
       +
               traceln "delay over";

     

       284
       +
               "a"

     

       285
       +
             )

     

       286
       +
             (fun () -> "b")

     

       287
       +
         in

     

       288
       +
         traceln "x = %S" x;;

     

       289
       +
       +first fiber delayed...

     

       290
       +
       +x = "b"

     

       291
       +
       - : unit = ()

     

       292
       +
       ```

     

       293
       +
       

     

       294
       +
       Note: using `Fiber.first` to ensure that *exactly one* of two actions is performed is not reliable.

     

       295
       +
       There is usually a possibility that both actions succeed at the same time (and one result is thrown away).

     

       296
       +
       For example, if you ask Eio read from two sockets with `io_uring`

     

       297
       +
       then the kernel may have already performed both reads by the time it tells Eio about the first one.

     

       298
       +
       

     

       299
       +
       ## Switches

     

       300
       +
       

     

       301
       +
       A [switch][Eio.Switch] is used to group fibers together, so they can be waited on together.

     

       302
       +
       This is a form of [structured concurrency][].

     

       303
       +
       For example:

     

       304
       +
       

     

       305
       +
       ```ocaml

     

       306
       +
       # Eio_main.run @@ fun _env ->

     

       307
       +
         Switch.run (fun sw ->

     

       308
       +
             for i = 1 to 3 do

     

       309
       +
               Fiber.fork ~sw (fun () ->

     

       310
       +
                   traceln "Job %d starting" i;

     

       311
       +
                   Fiber.yield ();

     

       312
       +
                   traceln "%d done" i;

     

       313
       +
                 );

     

       314
       +
             done;

     

       315
       +
             traceln "All child fibers forked";

     

       316
       +
           );

     

       317
       +
         traceln "Switch is finished";;

     

       318
       +
       +Job 1 starting

     

       319
       +
       +Job 2 starting

     

       320
       +
       +Job 3 starting

     

       321
       +
       +All child fibers forked

     

       322
       +
       +1 done

     

       323
       +
       +2 done

     

       324
       +
       +3 done

     

       325
       +
       +Switch is finished

     

       326
       +
       - : unit = ()

     

       327
       +
       ```

     

       328
       +
       

     

       329
       +
       <p align='center'>

     

       330
       +
         <img src="./doc/traces/switch-mock.svg"/>

     

       331
       +
       </p>

     

       332
       +
       

     

       333
       +
       `Switch.run fn` creates a new switch `sw` and runs `fn sw`.

     

       334
       +
       `fn` may spawn new fibers and attach them to the switch.

     

       335
       +
       It may also attach other resources such as open file handles.

     

       336
       +
       `Switch.run` waits until `fn` and all other attached fibers have finished, and then

     

       337
       +
       releases any attached resources (e.g. closing all attached file handles).

     

       338
       +
       

     

       339
       +
       If you call a function without giving it access to a switch,

     

       340
       +
       then when the function returns you can be sure that any fibers it spawned have finished,

     

       341
       +
       and any files it opened have been closed.

     

       342
       +
       This works because Eio does not provide e.g. a way to open a file without attaching it to a switch.

     

       343
       +
       If a function doesn't have a switch and wants to open a file, it must use `Switch.run` to create one.

     

       344
       +
       But then the function can't return until `Switch.run` does, at which point the file is closed.

     

       345
       +
       

     

       346
       +
       So, a `Switch.run` puts a bound on the lifetime of things created within it,

     

       347
       +
       leading to clearer code and avoiding resource leaks.

     

       348
       +
       The `Fiber.fork` call above creates a new fiber that continues running after `fork` returns,

     

       349
       +
       so it needs to take a switch argument.

     

       350
       +
       

     

       351
       +
       Every switch also creates a new cancellation context.

     

       352
       +
       You can use `Switch.fail` to mark the switch as failed and cancel all fibers within it.

     

       353
       +
       The exception (or exceptions) passed to `fail` will be raised by `run` when the fibers have exited.

     

       354
       +
       

     

       355
       +
       ## Networking

     

       356
       +
       

     

       357
       +
       Eio provides an API for [networking][Eio.Net].

     

       358
       +
       Here is a server connection handler that handles an incoming connection by sending the client a message:

     

       359
       +
       

     

       360
       +
       ```ocaml

     

       361
       +
       let handle_client flow _addr =

     

       362
       +
         traceln "Server: got connection from client";

     

       363
       +
         Eio.Flow.copy_string "Hello from server" flow

     

       364
       +
       ```

     

       365
       +
       

     

       366
       +
       We can test it using a mock flow:

     

       367
       +
       

     

       368
       +
       ```ocaml

     

       369
       +
       # Eio_mock.Backend.run @@ fun () ->

     

       370
       +
         let flow = Eio_mock.Flow.make "flow" in

     

       371
       +
         let addr = `Tcp (Eio.Net.Ipaddr.V4.loopback, 37568) in

     

       372
       +
         handle_client flow addr;;

     

       373
       +
       +Server: got connection from client

     

       374
       +
       +flow: wrote "Hello from server"

     

       375
       +
       - : unit = ()

     

       376
       +
       ```

     

       377
       +
       

     

       378
       +
       Note: `Eio_mock.Backend.run` can be used instead of `Eio_main.run` for tests that don't access the outside environment at all.

     

       379
       +
       It doesn't support multiple domains, but this allows it to detect deadlocks automatically

     

       380
       +
       (a multi-domain loop has to assume it might get an event from another domain, and so must keep waiting).

     

       381
       +
       

     

       382
       +
       Here is a client that connects to address `addr` using network `net` and reads a message:

     

       383
       +
       

     

       384
       +
       ```ocaml

     

       385
       +
       let run_client ~net ~addr =

     

       386
       +
         Switch.run ~name:"client" @@ fun sw ->

     

       387
       +
         traceln "Client: connecting to server";

     

       388
       +
         let flow = Eio.Net.connect ~sw net addr in

     

       389
       +
         (* Read all data until end-of-stream (shutdown): *)

     

       390
       +
         traceln "Client: received %S" (Eio.Flow.read_all flow)

     

       391
       +
       ```

     

       392
       +
       

     

       393
       +
       Note: the `flow` is attached to `sw` and will be closed automatically when it finishes.

     

       394
       +
       We also named the switch here; this will appear in the trace output (see below).

     

       395
       +
       

     

       396
       +
       This can also be tested on its own using a mock network:

     

       397
       +
       

     

       398
       +
       ```ocaml

     

       399
       +
       # Eio_mock.Backend.run @@ fun () ->

     

       400
       +
         let net = Eio_mock.Net.make "mocknet" in

     

       401
       +
         let flow = Eio_mock.Flow.make "flow" in

     

       402
       +
         Eio_mock.Net.on_connect net [`Return flow];

     

       403
       +
         Eio_mock.Flow.on_read flow [

     

       404
       +
           `Return "(packet 1)";

     

       405
       +
           `Yield_then (`Return "(packet 2)");

     

       406
       +
           `Raise End_of_file;

     

       407
       +
         ];

     

       408
       +
         let addr = `Tcp (Eio.Net.Ipaddr.V4.loopback, 8080) in

     

       409
       +
         run_client ~net ~addr;;

     

       410
       +
       +Client: connecting to server

     

       411
       +
       +mocknet: connect to tcp:127.0.0.1:8080

     

       412
       +
       +flow: read "(packet 1)"

     

       413
       +
       +flow: read "(packet 2)"

     

       414
       +
       +Client: received "(packet 1)(packet 2)"

     

       415
       +
       +flow: closed

     

       416
       +
       - : unit = ()

     

       417
       +
       ```

     

       418
       +
       

     

       419
       +
       `Eio.Net.run_server` runs a loop accepting clients and handling them (concurrently):

     

       420
       +
       

     

       421
       +
       ```ocaml

     

       422
       +
       let run_server socket =

     

       423
       +
         Eio.Net.run_server socket handle_client

     

       424
       +
           ~on_error:(traceln "Error handling connection: %a" Fmt.exn)

     

       425
       +
       ```

     

       426
       +
       

     

       427
       +
       Note: when `handle_client` finishes, `run_server` closes the flow automatically.

     

       428
       +
       

     

       429
       +
       We can now run the client and server together using the real network (in a single process):

     

       430
       +
       

     

       431
       +
       ```ocaml

     

       432
       +
       let main ~net ~addr =

     

       433
       +
         Switch.run ~name:"main" @@ fun sw ->

     

       434
       +
         let server = Eio.Net.listen net ~sw ~reuse_addr:true ~backlog:5 addr in

     

       435
       +
         Fiber.fork_daemon ~sw (fun () -> run_server server);

     

       436
       +
         run_client ~net ~addr

     

       437
       +
       ```

     

       438
       +
       

     

       439
       +
       `Fiber.fork_daemon` creates a new fiber and then cancels it when the switch finishes.

     

       440
       +
       We need that here because otherwise the server would keep waiting for new connections and

     

       441
       +
       the test would never finish.

     

       442
       +
       

     

       443
       +
       ```ocaml

     

       444
       +
       # Eio_main.run @@ fun env ->

     

       445
       +
         main

     

       446
       +
           ~net:(Eio.Stdenv.net env)

     

       447
       +
           ~addr:(`Tcp (Eio.Net.Ipaddr.V4.loopback, 8080));;

     

       448
       +
       +Client: connecting to server

     

       449
       +
       +Server: got connection from client

     

       450
       +
       +Client: received "Hello from server"

     

       451
       +
       - : unit = ()

     

       452
       +
       ```

     

       453
       +
       

     

       454
       +
       <p align='center'>

     

       455
       +
         <img src="./doc/traces/net-posix.svg"/>

     

       456
       +
       </p>

     

       457
       +
       

     

       458
       +
       See [examples/net](./examples/net/) for a more complete example.

     

       459
       +
       

     

       460
       +
       ## Design Note: Capabilities

     

       461
       +
       

     

       462
       +
       Eio follows the principles of capability-based security.

     

       463
       +
       The key idea here is that the lambda calculus already contains a perfectly good security system:

     

       464
       +
       a function can only access things that are in its scope.

     

       465
       +
       If we can avoid breaking this model (for example, by adding global variables to our language)

     

       466
       +
       then we can reason about the security properties of code quite easily.

     

       467
       +
       

     

       468
       +
       Consider the network example in the previous section.

     

       469
       +
       Imagine this is a large program and we want to know:

     

       470
       +
       

     

       471
       +
       1. Does this program modify the filesystem?

     

       472
       +
       2. Does this program send telemetry data over the network?

     

       473
       +
       

     

       474
       +
       In a capability-safe language, we don't have to read the entire code-base to find the answers:

     

       475
       +
       

     

       476
       +
       - All authority starts at the (privileged) `Eio_main.run` function with the `env` parameter,

     

       477
       +
         so we must check this code.

     

       478
       +
       

     

       479
       +
       - Only `env`'s network access is used, so we know this program doesn't access the filesystem,

     

       480
       +
         answering question 1 immediately.

     

       481
       +
       

     

       482
       +
       - To check whether telemetry is sent, we need to follow the `net` authority as it is passed to `main`.

     

       483
       +
       

     

       484
       +
       - `main` uses `net` to open a listening socket on the loopback interface, which it passes to `run_server`.

     

       485
       +
         `run_server` does not get the full `net` access, so we probably don't need to read that code; however,

     

       486
       +
         we might want to check whether we granted other parties access to this port on our loopback network.

     

       487
       +
       

     

       488
       +
       - `run_client` does get `net`, so we do need to read that.

     

       489
       +
         We could make that code easier to audit by passing it `(fun () -> Eio.Net.connect net addr)` instead of `net` .

     

       490
       +
         Then we could see that `run_client` could only connect to our loopback address.

     

       491
       +
       

     

       492
       +
       Since OCaml is not a capability language, code can ignore Eio and use the non-capability APIs directly.

     

       493
       +
       However, it still makes non-malicious code easier to understand and test,

     

       494
       +
       and may allow for an extension to the language in the future.

     

       495
       +
       

     

       496
       +
       The [Lambda Capabilities][] blog post provides a more detailed introduction to capabilities,

     

       497
       +
       written for functional programmers.

     

       498
       +
       

     

       499
       +
       ## Buffered Reading and Parsing

     

       500
       +
       

     

       501
       +
       Reading from an Eio flow directly may give you more or less data than you wanted.

     

       502
       +
       For example, if you want to read a line of text from a TCP stream,

     

       503
       +
       the flow will tend to give you the data in packet-sized chunks, not lines.

     

       504
       +
       To solve this, you can wrap the flow with a [buffer][Eio.Buf_read] and read from that.

     

       505
       +
       

     

       506
       +
       Here's a simple command-line interface that reads `stdin` one line at a time:

     

       507
       +
       

     

       508
       +
       ```ocaml

     

       509
       +
       let cli ~stdin ~stdout =

     

       510
       +
         let buf = Eio.Buf_read.of_flow stdin ~initial_size:100 ~max_size:1_000_000 in

     

       511
       +
         while true do

     

       512
       +
           let line = Eio.Buf_read.line buf in

     

       513
       +
           traceln "> %s" line;

     

       514
       +
           match line with

     

       515
       +
           | "h" | "help" -> Eio.Flow.copy_string "It's just an example\n" stdout

     

       516
       +
           | x -> Eio.Flow.copy_string (Fmt.str "Unknown command %S\n" x) stdout

     

       517
       +
         done

     

       518
       +
       ```

     

       519
       +
       

     

       520
       +
       Let's try it with some test data (you could use the real stdin if you prefer):

     

       521
       +
       

     

       522
       +
       ```ocaml

     

       523
       +
       # Eio_main.run @@ fun env ->

     

       524
       +
         cli

     

       525
       +
           ~stdin:(Eio.Flow.string_source "help\nexit\nquit\nbye\nstop\n")

     

       526
       +
           ~stdout:(Eio.Stdenv.stdout env);;

     

       527
       +
       +> help

     

       528
       +
       It's just an example

     

       529
       +
       +> exit

     

       530
       +
       Unknown command "exit"

     

       531
       +
       +> quit

     

       532
       +
       Unknown command "quit"

     

       533
       +
       +> bye

     

       534
       +
       Unknown command "bye"

     

       535
       +
       +> stop

     

       536
       +
       Unknown command "stop"

     

       537
       +
       Exception: End_of_file.

     

       538
       +
       ```

     

       539
       +
       

     

       540
       +
       `Buf_read.of_flow` allocates an internal buffer (with the given `initial_size`).

     

       541
       +
       When you try to read a line from it, it will take a whole line from the buffer if possible.

     

       542
       +
       If not, it will ask the underlying flow for the next chunk of data, until it has enough.

     

       543
       +
       

     

       544
       +
       For high performance applications, you should use a larger initial buffer

     

       545
       +
       so that fewer reads on the underlying flow are needed.

     

       546
       +
       

     

       547
       +
       If the user enters a line that doesn't fit in the buffer then the buffer will be enlarged as needed.

     

       548
       +
       However, it will raise an exception if the buffer would need to grow above `max_size`.

     

       549
       +
       This is useful when handling untrusted input, since otherwise when you try to read one line an

     

       550
       +
       attacker could just keep sending e.g. 'x' characters until your service ran out of memory and crashed.

     

       551
       +
       

     

       552
       +
       As well as calling individual parsers (like `line`) directly,

     

       553
       +
       you can also build larger parsers from smaller ones.

     

       554
       +
       For example:

     

       555
       +
       

     

       556
       +
       ```ocaml

     

       557
       +
       open Eio.Buf_read.Syntax

     

       558
       +
       

     

       559
       +
       type message = { src : string; body : string }

     

       560
       +
       

     

       561
       +
       let message =

     

       562
       +
         let+ src = Eio.Buf_read.(string "FROM:" *> line)

     

       563
       +
         and+ body = Eio.Buf_read.take_all in

     

       564
       +
         { src; body }

     

       565
       +
       ```

     

       566
       +
       

     

       567
       +
       ```ocaml

     

       568
       +
       # Eio_main.run @@ fun _ ->

     

       569
       +
         let flow = Eio.Flow.string_source "FROM:Alice\nHello!\n" in

     

       570
       +
         match Eio.Buf_read.parse message flow ~max_size:1024 with

     

       571
       +
         | Ok { src; body } -> traceln "%s sent %S" src body

     

       572
       +
         | Error (`Msg err) -> traceln "Parse failed: %s" err;;

     

       573
       +
       +Alice sent "Hello!\n"

     

       574
       +
       - : unit = ()

     

       575
       +
       ```

     

       576
       +
       

     

       577
       +
       ## Buffered Writing

     

       578
       +
       

     

       579
       +
       For performance, it's often useful to batch up writes and send them all in one go.

     

       580
       +
       For example, consider sending an HTTP response without buffering:

     

       581
       +
       

     

       582
       +
       ```ocaml

     

       583
       +
       let send_response socket =

     

       584
       +
         Eio.Flow.copy_string "HTTP/1.1 200 OK\r\n" socket;

     

       585
       +
         Eio.Flow.copy_string "\r\n" socket;

     

       586
       +
         Fiber.yield ();       (* Simulate delayed generation of body *)

     

       587
       +
         Eio.Flow.copy_string "Body data" socket

     

       588
       +
       ```

     

       589
       +
       

     

       590
       +
       ```ocaml

     

       591
       +
       # Eio_main.run @@ fun _ ->

     

       592
       +
         send_response (Eio_mock.Flow.make "socket");;

     

       593
       +
       +socket: wrote "HTTP/1.1 200 OK\r\n"

     

       594
       +
       +socket: wrote "\r\n"

     

       595
       +
       +socket: wrote "Body data"

     

       596
       +
       - : unit = ()

     

       597
       +
       ```

     

       598
       +
       

     

       599
       +
       The socket received three writes, perhaps sending three separate packets over the network.

     

       600
       +
       We can wrap a flow with [Eio.Buf_write][] to avoid this:

     

       601
       +
       

     

       602
       +
       ```ocaml

     

       603
       +
       module Write = Eio.Buf_write

     

       604
       +
       

     

       605
       +
       let send_response socket =

     

       606
       +
         Write.with_flow socket @@ fun w ->

     

       607
       +
         Write.string w "HTTP/1.1 200 OK\r\n";

     

       608
       +
         Write.string w "\r\n";

     

       609
       +
         Fiber.yield ();       (* Simulate delayed generation of body *)

     

       610
       +
         Write.string w "Body data"

     

       611
       +
       ```

     

       612
       +
       

     

       613
       +
       ```ocaml

     

       614
       +
       # Eio_main.run @@ fun _ ->

     

       615
       +
         send_response (Eio_mock.Flow.make "socket");;

     

       616
       +
       +socket: wrote "HTTP/1.1 200 OK\r\n"

     

       617
       +
       +              "\r\n"

     

       618
       +
       +socket: wrote "Body data"

     

       619
       +
       - : unit = ()

     

       620
       +
       ```

     

       621
       +
       

     

       622
       +
       Now the first two writes were combined and sent together.

     

       623
       +
       

     

       624
       +
       ## Error Handling

     

       625
       +
       

     

       626
       +
       Errors interacting with the outside world are indicated by the `Eio.Io (err, context)` exception.

     

       627
       +
       This is roughly equivalent to the `Unix.Unix_error` exception from the OCaml standard library.

     

       628
       +
       

     

       629
       +
       The `err` field describes the error using nested error codes,

     

       630
       +
       allowing you to match on either specific errors or whole classes of errors at once.

     

       631
       +
       For example:

     

       632
       +
       

     

       633
       +
       ```ocaml

     

       634
       +
       let test r =

     

       635
       +
         try Eio.Buf_read.line r

     

       636
       +
         with

     

       637
       +
         | Eio.Io (Eio.Net.E Connection_reset Eio_unix.Unix_error _, _) -> "Unix connection reset"

     

       638
       +
         | Eio.Io (Eio.Net.E Connection_reset _, _) -> "Connection reset"

     

       639
       +
         | Eio.Io (Eio.Net.E _, _) -> "Some network error"

     

       640
       +
         | Eio.Io _ -> "Some I/O error"

     

       641
       +
       ```

     

       642
       +
       

     

       643
       +
       For portable code, you will want to avoid matching backend-specific errors, so you would avoid the first case.

     

       644
       +
       The `Eio.Io` type is extensible, so libraries can also add additional top-level error types if needed.

     

       645
       +
       

     

       646
       +
       `Io` errors also allow adding extra context information to the error.

     

       647
       +
       For example, this HTTP GET function adds the URL to any IO error:

     

       648
       +
       

     

       649
       +
       ```ocaml

     

       650
       +
       let get ~net ~host ~path =

     

       651
       +
         try

     

       652
       +
           Eio.Net.with_tcp_connect net ~host ~service:"http" @@ fun _flow ->

     

       653
       +
           "..."

     

       654
       +
         with Eio.Io _ as ex ->

     

       655
       +
           let bt = Printexc.get_raw_backtrace () in

     

       656
       +
           Eio.Exn.reraise_with_context ex bt "fetching http://%s/%s" host path;;

     

       657
       +
       ```

     

       658
       +
       

     

       659
       +
       If we test it using a mock network that returns a timeout,

     

       660
       +
       we get a useful error message telling us the IP address and port of the failed attempt,

     

       661
       +
       extended with the hostname we used to get that,

     

       662
       +
       and then extended again by our `get` function with the full URL:

     

       663
       +
       

     

       664
       +
       ```ocaml

     

       665
       +
       # Eio_mock.Backend.run @@ fun () ->

     

       666
       +
         let net = Eio_mock.Net.make "mocknet" in

     

       667
       +
         Eio_mock.Net.on_getaddrinfo net [`Return [`Tcp (Eio.Net.Ipaddr.V4.loopback, 80)]];

     

       668
       +
         Eio_mock.Net.on_connect net [`Raise (Eio.Net.err (Connection_failure Timeout))];

     

       669
       +
         get ~net ~host:"example.com" ~path:"index.html";;

     

       670
       +
       +mocknet: getaddrinfo ~service:http example.com

     

       671
       +
       +mocknet: connect to tcp:127.0.0.1:80

     

       672
       +
       Exception:

     

       673
       +
       Eio.Io Net Connection_failure Timeout,

     

       674
       +
         connecting to tcp:127.0.0.1:80,

     

       675
       +
         connecting to "example.com":http,

     

       676
       +
         fetching http://example.com/index.html

     

       677
       +
       ```

     

       678
       +
       

     

       679
       +
       To get more detailed information, you can enable backtraces by setting `OCAMLRUNPARAM=b`

     

       680
       +
       or by calling `Printexc.record_backtrace true`, as usual.

     

       681
       +
       

     

       682
       +
       When writing MDX tests that depend on getting the exact error output,

     

       683
       +
       it can be annoying to have the full backend-specific error displayed:

     

       684
       +
       

     

       685
       +
       <!-- $MDX non-deterministic=command -->

     

       686
       +
       ```ocaml

     

       687
       +
       # Eio_main.run @@ fun env ->

     

       688
       +
         let net = Eio.Stdenv.net env in

     

       689
       +
         Switch.run @@ fun sw ->

     

       690
       +
         Eio.Net.connect ~sw net (`Tcp (Eio.Net.Ipaddr.V4.loopback, 1234));;

     

       691
       +
       Exception:

     

       692
       +
       Eio.Io Net Connection_failure Refused Unix_error (Connection refused, "connect", ""),

     

       693
       +
         connecting to tcp:127.0.0.1:1234

     

       694
       +
       ```

     

       695
       +
       

     

       696
       +
       If we ran this using another backend, the `Unix_error` part might change.

     

       697
       +
       To avoid this problem, you can use `Eio.Exn.Backend.show` to hide the backend-specific part of errors:

     

       698
       +
       

     

       699
       +
       ```ocaml

     

       700
       +
       # Eio.Exn.Backend.show := false;;

     

       701
       +
       - : unit = ()

     

       702
       +
       

     

       703
       +
       # Eio_main.run @@ fun env ->

     

       704
       +
         let net = Eio.Stdenv.net env in

     

       705
       +
         Switch.run @@ fun sw ->

     

       706
       +
         Eio.Net.connect ~sw net (`Tcp (Eio.Net.Ipaddr.V4.loopback, 1234));;

     

       707
       +
       Exception:

     

       708
       +
       Eio.Io Net Connection_failure Refused _,

     

       709
       +
         connecting to tcp:127.0.0.1:1234

     

       710
       +
       ```

     

       711
       +
       

     

       712
       +
       We'll leave it like that for the rest of this file,

     

       713
       +
       so the examples can be tested automatically by MDX.

     

       714
       +
       

     

       715
       +
       ## Filesystem Access

     

       716
       +
       

     

       717
       +
       Access to the filesystem is performed using [Eio.Path][].

     

       718
       +
       An `'a Path.t` is a pair of a capability to a base directory (of type `'a`) and a string path relative to that.

     

       719
       +
       To append to the string part, it's convenient to use the `/` operator:

     

       720
       +
       

     

       721
       +
       ```ocaml

     

       722
       +
       let ( / ) = Eio.Path.( / )

     

       723
       +
       ```

     

       724
       +
       

     

       725
       +
       <!--

     

       726
       +
       Cleanup previous runs due to [dune runtest --watch] not doing it

     

       727
       +
       ```ocaml

     

       728
       +
       Eio_main.run @@ fun env ->

     

       729
       +
       let cwd = Eio.Stdenv.cwd env in

     

       730
       +
       ["link-to-dir1"; "link-to-tmp"; "test.txt"; "dir1"]

     

       731
       +
       |> List.iter (fun p -> Eio.Path.rmtree ~missing_ok:true (cwd / p))

     

       732
       +
       ```

     

       733
       +
       -->

     

       734
       +
       

     

       735
       +
       `env` provides two initial paths:

     

       736
       +
       

     

       737
       +
       - `cwd` restricts access to files beneath the current working directory.

     

       738
       +
       - `fs` provides full access (just like OCaml's stdlib).

     

       739
       +
       

     

       740
       +
       You can save a whole file using `Path.save`:

     

       741
       +
       

     

       742
       +
       ```ocaml

     

       743
       +
       # Eio_main.run @@ fun env ->

     

       744
       +
         let path = Eio.Stdenv.cwd env / "test.txt" in

     

       745
       +
         traceln "Saving to %a" Eio.Path.pp path;

     

       746
       +
         Eio.Path.save ~create:(`Exclusive 0o600) path "line one\nline two\n";;

     

       747
       +
       +Saving to <cwd:test.txt>

     

       748
       +
       - : unit = ()

     

       749
       +
       ```

     

       750
       +
       

     

       751
       +
       For more control, use `Path.open_out` (or `with_open_out`) to get a flow.

     

       752
       +
       

     

       753
       +
       To load a file, you can use `load` to read the whole thing into a string,

     

       754
       +
       `Path.open_in` (or `with_open_in`) to get a flow, or `Path.with_lines` to stream

     

       755
       +
       the lines (a convenience function that uses `Buf_read.lines`):

     

       756
       +
       

     

       757
       +
       ```ocaml

     

       758
       +
       # Eio_main.run @@ fun env ->

     

       759
       +
         let path = Eio.Stdenv.cwd env / "test.txt" in

     

       760
       +
         Eio.Path.with_lines path (fun lines ->

     

       761
       +
            Seq.iter (traceln "Processing %S") lines

     

       762
       +
         );;

     

       763
       +
       +Processing "line one"

     

       764
       +
       +Processing "line two"

     

       765
       +
       - : unit = ()

     

       766
       +
       ```

     

       767
       +
       

     

       768
       +
       Access to `cwd` only grants access to that sub-tree:

     

       769
       +
       

     

       770
       +
       ```ocaml

     

       771
       +
       let try_save path data =

     

       772
       +
         match Eio.Path.save ~create:(`Exclusive 0o600) path data with

     

       773
       +
         | () -> traceln "save %a : ok" Eio.Path.pp path

     

       774
       +
         | exception ex -> traceln "%a" Eio.Exn.pp ex

     

       775
       +
       

     

       776
       +
       let try_mkdir path =

     

       777
       +
         match Eio.Path.mkdir path ~perm:0o700 with

     

       778
       +
         | () -> traceln "mkdir %a : ok" Eio.Path.pp path

     

       779
       +
         | exception ex -> traceln "%a" Eio.Exn.pp ex

     

       780
       +
       ```

     

       781
       +
       

     

       782
       +
       ```ocaml

     

       783
       +
       # Eio_main.run @@ fun env ->

     

       784
       +
         let cwd = Eio.Stdenv.cwd env in

     

       785
       +
         try_mkdir (cwd / "dir1");

     

       786
       +
         try_mkdir (cwd / "../dir2");

     

       787
       +
         try_mkdir (cwd / "/tmp/dir3");;

     

       788
       +
       +mkdir <cwd:dir1> : ok

     

       789
       +
       +Eio.Io Fs Permission_denied _, creating directory <cwd:../dir2>

     

       790
       +
       +Eio.Io Fs Permission_denied _, creating directory <cwd:/tmp/dir3>

     

       791
       +
       - : unit = ()

     

       792
       +
       ```

     

       793
       +
       

     

       794
       +
       The checks also apply to following symlinks:

     

       795
       +
       

     

       796
       +
       ```ocaml

     

       797
       +
       # Unix.symlink "dir1" "link-to-dir1";

     

       798
       +
         Unix.symlink (Filename.get_temp_dir_name ()) "link-to-tmp";;

     

       799
       +
       - : unit = ()

     

       800
       +
       

     

       801
       +
       # Eio_main.run @@ fun env ->

     

       802
       +
         let cwd = Eio.Stdenv.cwd env in

     

       803
       +
         try_save (cwd / "dir1/file1") "A";

     

       804
       +
         try_save (cwd / "link-to-dir1/file2") "B";

     

       805
       +
         try_save (cwd / "link-to-tmp/file3") "C";;

     

       806
       +
       +save <cwd:dir1/file1> : ok

     

       807
       +
       +save <cwd:link-to-dir1/file2> : ok

     

       808
       +
       +Eio.Io Fs Permission_denied _, opening <cwd:link-to-tmp/file3>

     

       809
       +
       - : unit = ()

     

       810
       +
       ```

     

       811
       +
       

     

       812
       +
       You can use `open_dir` (or `with_open_dir`) to create a restricted capability to a subdirectory:

     

       813
       +
       

     

       814
       +
       ```ocaml

     

       815
       +
       # Eio_main.run @@ fun env ->

     

       816
       +
         let cwd = Eio.Stdenv.cwd env in

     

       817
       +
         Eio.Path.with_open_dir (cwd / "dir1") @@ fun dir1 ->

     

       818
       +
         try_save (dir1 / "file4") "D";

     

       819
       +
         try_save (dir1 / "../file5") "E";;

     

       820
       +
       +save <dir1:file4> : ok

     

       821
       +
       +Eio.Io Fs Permission_denied _, opening <dir1:../file5>

     

       822
       +
       - : unit = ()

     

       823
       +
       ```

     

       824
       +
       

     

       825
       +
       You only need to use `open_dir` if you want to create a new sandboxed environment.

     

       826
       +
       You can use a single base directory object to access all paths beneath it,

     

       827
       +
       and this allows following symlinks within that subtree.

     

       828
       +
       

     

       829
       +
       A program that operates on the current directory will probably want to use `cwd`,

     

       830
       +
       whereas a program that accepts a path from the user will probably want to use `fs`,

     

       831
       +
       perhaps with `open_dir` to constrain all access to be within that directory.

     

       832
       +
       

     

       833
       +
       On systems that provide the [cap_enter][] system call, you can ask the OS to reject accesses

     

       834
       +
       that don't use capabilities.

     

       835
       +
       [examples/capsicum/](./examples/capsicum/) contains an example that

     

       836
       +
       restricts itself to using a directory passed on the command-line, and then

     

       837
       +
       tries reading `/etc/passwd` via the stdlib.

     

       838
       +
       Running on FreeBSD, you should see:

     

       839
       +
       

     

       840
       +
       ```

     

       841
       +
       mkdir /tmp/cap

     

       842
       +
       dune exec -- ./examples/capsicum/main.exe /tmp/cap

     

       843
       +
       +Opened directory <fs:/tmp/cap>        

     

       844
       +
       +Capsicum mode enabled

     

       845
       +
       +Using the file-system via the directory resource works:

     

       846
       +
       +Writing <cap:capsicum-test.txt>...

     

       847
       +
       +Read: "A test file"

     

       848
       +
       +Bypassing Eio and accessing other resources should fail in Capsicum mode:

     

       849
       +
       Fatal error: exception Sys_error("/etc/passwd: Not permitted in capability mode")

     

       850
       +
       ```

     

       851
       +
       

     

       852
       +
       ## Running processes

     

       853
       +
       

     

       854
       +
       Spawning a child process can be done using the [Eio.Process][] module:

     

       855
       +
       

     

       856
       +
       ```ocaml

     

       857
       +
       # Eio_main.run @@ fun env ->

     

       858
       +
         let proc_mgr = Eio.Stdenv.process_mgr env in

     

       859
       +
         Eio.Process.run proc_mgr ["echo"; "hello"];;

     

       860
       +
       hello

     

       861
       +
       - : unit = ()

     

       862
       +
       ```

     

       863
       +
       

     

       864
       +
       There are various optional arguments for setting the process's current directory or connecting up the standard streams.

     

       865
       +
       For example, we can use `tr` to convert some text to upper-case:

     

       866
       +
       

     

       867
       +
       ```ocaml

     

       868
       +
       # Eio_main.run @@ fun env ->

     

       869
       +
         let proc_mgr = Eio.Stdenv.process_mgr env in

     

       870
       +
         Eio.Process.run proc_mgr ["tr"; "a-z"; "A-Z"]

     

       871
       +
           ~stdin:(Eio.Flow.string_source "One two three\n");;

     

       872
       +
       ONE TWO THREE

     

       873
       +
       - : unit = ()

     

       874
       +
       ```

     

       875
       +
       

     

       876
       +
       If you want to capture the output of a process, you can provide a suitable `Eio.Flow.sink` as the `stdout` argument,

     

       877
       +
       or use the `parse_out` convenience wrapper:

     

       878
       +
       

     

       879
       +
       ```ocaml

     

       880
       +
       # Eio_main.run @@ fun env ->

     

       881
       +
         let proc_mgr = Eio.Stdenv.process_mgr env in

     

       882
       +
         Eio.Process.parse_out proc_mgr Eio.Buf_read.line ["echo"; "hello"];;

     

       883
       +
       - : string = "hello"

     

       884
       +
       ```

     

       885
       +
       

     

       886
       +
       All process functions either return the exit status or check that it was zero (success):

     

       887
       +
       

     

       888
       +
       ```ocaml

     

       889
       +
       # Eio_main.run @@ fun env ->

     

       890
       +
         let proc_mgr = Eio.Stdenv.process_mgr env in

     

       891
       +
         Eio.Process.parse_out proc_mgr Eio.Buf_read.take_all ["sh"; "-c"; "exit 3"];;

     

       892
       +
       Exception:

     

       893
       +
       Eio.Io Process Child_error Exited (code 3),

     

       894
       +
         running command: sh -c "exit 3"

     

       895
       +
       ```

     

       896
       +
       

     

       897
       +
       `Process.spawn` and `Process.await` give more control over the process's lifetime

     

       898
       +
       and exit status, and `Eio_unix.Process` gives more control over passing file

     

       899
       +
       descriptors (on systems that support them).

     

       900
       +
       

     

       901
       +
       ## Time

     

       902
       +
       

     

       903
       +
       The standard environment provides a [clock][Eio.Time] with the usual POSIX time:

     

       904
       +
       

     

       905
       +
       ```ocaml

     

       906
       +
       # Eio_main.run @@ fun env ->

     

       907
       +
         let clock = Eio.Stdenv.clock env in

     

       908
       +
         traceln "The time is now %f" (Eio.Time.now clock);;

     

       909
       +
       +The time is now 1623940778.270336

     

       910
       +
       - : unit = ()

     

       911
       +
       ```

     

       912
       +
       

     

       913
       +
       The mock backend provides a mock clock that advances automatically where there is nothing left to do:

     

       914
       +
       

     

       915
       +
       ```ocaml

     

       916
       +
       # Eio_mock.Backend.run_full @@ fun env ->

     

       917
       +
         let clock = Eio.Stdenv.clock env in

     

       918
       +
         traceln "Sleeping for five seconds...";

     

       919
       +
         Eio.Time.sleep clock 5.0;

     

       920
       +
         traceln "Resumed";;

     

       921
       +
       +Sleeping for five seconds...

     

       922
       +
       +mock time is now 5

     

       923
       +
       +Resumed

     

       924
       +
       - : unit = ()

     

       925
       +
       ```

     

       926
       +
       

     

       927
       +
       Note: You could also just use `Eio_unix.sleep 5.0` if you don't want to pass a clock around.

     

       928
       +
       This is especially useful if you need to insert a delay for some quick debugging.

     

       929
       +
       

     

       930
       +
       ## Multicore Support

     

       931
       +
       

     

       932
       +
       OCaml allows a program to create multiple *domains* in which to run code, allowing multiple CPUs to be used at once.

     

       933
       +
       Fibers are scheduled cooperatively within a single domain, but fibers in different domains run in parallel.

     

       934
       +
       This is useful to perform CPU-intensive operations quickly

     

       935
       +
       (though extra care needs to be taken when using multiple cores; see the [Multicore Guide](./doc/multicore.md) for details).

     

       936
       +
       

     

       937
       +
       ### Domain Manager

     

       938
       +
       

     

       939
       +
       [Eio.Domain_manager][] provides a basic API for spawning domains.

     

       940
       +
       For example, let's say we have a CPU intensive task:

     

       941
       +
       

     

       942
       +
       ```ocaml

     

       943
       +
       let sum_to n =

     

       944
       +
         traceln "Starting CPU-intensive task...";

     

       945
       +
         let total = ref 0 in

     

       946
       +
         for i = 1 to n do

     

       947
       +
           total := !total + i

     

       948
       +
         done;

     

       949
       +
         traceln "Finished";

     

       950
       +
         !total

     

       951
       +
       ```

     

       952
       +
       

     

       953
       +
       We can use the domain manager to run this in a separate domain:

     

       954
       +
       

     

       955
       +
       ```ocaml

     

       956
       +
       let main ~domain_mgr =

     

       957
       +
         let test n =

     

       958
       +
           traceln "sum 1..%d = %d" n

     

       959
       +
             (Eio.Domain_manager.run domain_mgr

     

       960
       +
               (fun () -> sum_to n))

     

       961
       +
         in

     

       962
       +
         Fiber.both

     

       963
       +
           (fun () -> test 100000)

     

       964
       +
           (fun () -> test 50000)

     

       965
       +
       ```

     

       966
       +
       

     

       967
       +
       <!-- $MDX non-deterministic=output -->

     

       968
       +
       ```ocaml

     

       969
       +
       # Eio_main.run @@ fun env ->

     

       970
       +
         main ~domain_mgr:(Eio.Stdenv.domain_mgr env);;

     

       971
       +
       +Starting CPU-intensive task...

     

       972
       +
       +Starting CPU-intensive task...

     

       973
       +
       +Finished

     

       974
       +
       +sum 1..50000 = 1250025000

     

       975
       +
       +Finished

     

       976
       +
       +sum 1..100000 = 5000050000

     

       977
       +
       - : unit = ()

     

       978
       +
       ```

     

       979
       +
       

     

       980
       +
       <p align='center'>

     

       981
       +
         <img src="./doc/traces/multicore-posix.svg"/>

     

       982
       +
       </p>

     

       983
       +
       

     

       984
       +
       Notes:

     

       985
       +
       

     

       986
       +
       - `traceln` can be used safely from multiple domains.

     

       987
       +
         It takes a mutex, so that trace lines are output atomically.

     

       988
       +
       - The exact `traceln` output of this example is non-deterministic,

     

       989
       +
         because the OS is free to schedule domains as it likes.

     

       990
       +
       - You must ensure that the function passed to `run` doesn't have access to any non-threadsafe values.

     

       991
       +
         The type system does not check this.

     

       992
       +
       - `Domain_manager.run` waits for the domain to finish, but it allows other fibers to run while waiting.

     

       993
       +
         This is why we use `Fiber.both` to create multiple fibers.

     

       994
       +
       

     

       995
       +
       ### Executor Pool

     

       996
       +
       

     

       997
       +
       An [Eio.Executor_pool][] distributes jobs among a pool of domain workers.

     

       998
       +
       Domains are reused and can execute multiple jobs concurrently.

     

       999
       +
       

     

       1000
       +
       Each domain worker starts new jobs until the total `~weight` of its running jobs reaches `1.0`.

     

       1001
       +
       The `~weight` represents the expected proportion of a CPU core that the job will take up.

     

       1002
       +
       Jobs are queued up if they cannot be started immediately due to all domain workers being busy (`>= 1.0`).

     

       1003
       +
       

     

       1004
       +
       This is the recommended way of leveraging OCaml 5's multicore capabilities.

     

       1005
       +
       

     

       1006
       +
       Usually you will only want one pool for an entire application, so the pool is typically created when the application starts:

     

       1007
       +
       

     

       1008
       +
       <!-- $MDX skip -->

     

       1009
       +
       ```ocaml

     

       1010
       +
       let () =

     

       1011
       +
         Eio_main.run @@ fun env ->

     

       1012
       +
         Switch.run @@ fun sw ->

     

       1013
       +
         let dm = Eio.Stdenv.domain_mgr env in

     

       1014
       +
         main ~pool:(Eio.Executor_pool.create ~sw ~domain_count:2 dm)

     

       1015
       +
       ```

     

       1016
       +
       

     

       1017
       +
       The pool starts its domain workers immediately upon creation.

     

       1018
       +
       

     

       1019
       +
       The pool will not block our switch `sw` from completing;

     

       1020
       +
       when the switch finishes, all domain workers and running jobs are cancelled.

     

       1021
       +
       

     

       1022
       +
       `~domain_count` is the number of domain workers to create.

     

       1023
       +
       The total number of domains should not exceed `Domain.recommended_domain_count` or the number of cores on your system.

     

       1024
       +
       

     

       1025
       +
       We can run the previous example using an Executor Pool like this:

     

       1026
       +
       

     

       1027
       +
       ```ocaml

     

       1028
       +
       let main ~pool =

     

       1029
       +
         let test n =

     

       1030
       +
           traceln "sum 1..%d = %d" n

     

       1031
       +
             (Eio.Executor_pool.submit_exn pool ~weight:1.0

     

       1032
       +
               (fun () -> sum_to n))

     

       1033
       +
         in

     

       1034
       +
         Fiber.both

     

       1035
       +
           (fun () -> test 100000)

     

       1036
       +
           (fun () -> test 50000)

     

       1037
       +
       ```

     

       1038
       +
       

     

       1039
       +
       <!-- $MDX non-deterministic=output -->

     

       1040
       +
       ```ocaml

     

       1041
       +
       # Eio_main.run @@ fun env ->

     

       1042
       +
         Switch.run @@ fun sw ->

     

       1043
       +
         let dm = Eio.Stdenv.domain_mgr env in

     

       1044
       +
         main ~pool:(Eio.Executor_pool.create ~sw ~domain_count:2 dm)

     

       1045
       +
       +Starting CPU-intensive task...

     

       1046
       +
       +Starting CPU-intensive task...

     

       1047
       +
       +Finished

     

       1048
       +
       +sum 1..50000 = 1250025000

     

       1049
       +
       +Finished

     

       1050
       +
       +sum 1..100000 = 5000050000

     

       1051
       +
       - : unit = ()

     

       1052
       +
       ```

     

       1053
       +
       `~weight` is the anticipated proportion of a CPU core used by the job.

     

       1054
       +
       In other words, the fraction of time actively spent executing OCaml code, not just waiting for I/O or system calls.

     

       1055
       +
       In the above code snippet we use `~weight:1.0` because the job is entirely CPU-bound: it never waits for I/O or other syscalls.

     

       1056
       +
       `~weight` must be `>= 0.0` and `<= 1.0`.

     

       1057
       +
       Example: given an IO-bound job that averages 2% of one CPU core, pass `~weight:0.02`.

     

       1058
       +
       

     

       1059
       +
       Each domain worker starts new jobs until the total `~weight` of its running jobs reaches `1.0`.

     

       1060
       +
        

     

       1061
       +
       ## Synchronisation Tools

     

       1062
       +
       

     

       1063
       +
       Eio provides several sub-modules for communicating between fibers,

     

       1064
       +
       and these work even when the fibers are running in different domains.

     

       1065
       +
       

     

       1066
       +
       ### Promises

     

       1067
       +
       

     

       1068
       +
       [Promises][Eio.Promise] are a simple and reliable way to communicate between fibers.

     

       1069
       +
       One fiber can wait for a promise and another can resolve it:

     

       1070
       +
       

     

       1071
       +
       ```ocaml

     

       1072
       +
       # Eio_main.run @@ fun _ ->

     

       1073
       +
         let promise, resolver = Promise.create () in

     

       1074
       +
         Fiber.both

     

       1075
       +
           (fun () ->

     

       1076
       +
             traceln "Waiting for promise...";

     

       1077
       +
             let x = Promise.await promise in

     

       1078
       +
             traceln "x = %d" x

     

       1079
       +
           )

     

       1080
       +
           (fun () ->

     

       1081
       +
             traceln "Resolving promise";

     

       1082
       +
             Promise.resolve resolver 42

     

       1083
       +
           );;

     

       1084
       +
       +Waiting for promise...

     

       1085
       +
       +Resolving promise

     

       1086
       +
       +x = 42

     

       1087
       +
       - : unit = ()

     

       1088
       +
       ```

     

       1089
       +
       

     

       1090
       +
       A promise is initially "unresolved", and can only be resolved once.

     

       1091
       +
       Awaiting a promise that is already resolved immediately returns the resolved value.

     

       1092
       +
       

     

       1093
       +
       Promises are one of the easiest tools to use safely:

     

       1094
       +
       it doesn't matter whether you wait on a promise before or after it is resolved,

     

       1095
       +
       and multiple fibers can wait for the same promise and will get the same result.

     

       1096
       +
       Promises are thread-safe; you can wait for a promise in one domain and resolve it in another.

     

       1097
       +
       

     

       1098
       +
       Promises are also useful for integrating with callback-based libraries. For example:

     

       1099
       +
       

     

       1100
       +
       ```ocaml

     

       1101
       +
       let wrap fn x =

     

       1102
       +
         let promise, resolver = Promise.create () in

     

       1103
       +
         fn x

     

       1104
       +
           ~on_success:(Promise.resolve_ok resolver)

     

       1105
       +
           ~on_error:(Promise.resolve_error resolver);

     

       1106
       +
         Promise.await_exn promise

     

       1107
       +
       ```

     

       1108
       +
       

     

       1109
       +
       ### Example: Concurrent Cache

     

       1110
       +
       

     

       1111
       +
       Here's an example using promises to cache lookups,

     

       1112
       +
       with the twist that another user might ask the cache for the value while it's still adding it.

     

       1113
       +
       We don't want to start a second fetch in that case, so instead we just store promises in the cache:

     

       1114
       +
       

     

       1115
       +
       ```ocaml

     

       1116
       +
       let make_cache fn =

     

       1117
       +
         let tbl = Hashtbl.create 10 in

     

       1118
       +
         fun key ->

     

       1119
       +
           match Hashtbl.find_opt tbl key with

     

       1120
       +
           | Some p -> Promise.await_exn p

     

       1121
       +
           | None ->

     

       1122
       +
             let p, r = Promise.create () in

     

       1123
       +
             Hashtbl.add tbl key p;

     

       1124
       +
             match fn key with

     

       1125
       +
             | v -> Promise.resolve_ok r v; v

     

       1126
       +
             | exception ex -> Promise.resolve_error r ex; raise ex

     

       1127
       +
       ```

     

       1128
       +
       

     

       1129
       +
       Notice that we store the new promise in the cache immediately,

     

       1130
       +
       without doing anything that might switch to another fiber.

     

       1131
       +
       

     

       1132
       +
       We can use it like this:

     

       1133
       +
       

     

       1134
       +
       ```ocaml

     

       1135
       +
       # let fetch url =

     

       1136
       +
           traceln "Fetching %S..." url;

     

       1137
       +
           Fiber.yield ();             (* Simulate work... *)

     

       1138
       +
           traceln "Got response for %S" url;

     

       1139
       +
           if url = "http://example.com" then "<h1>Example.com</h1>"

     

       1140
       +
           else failwith "404 Not Found";;

     

       1141
       +
       val fetch : string -> string = <fun>

     

       1142
       +
       

     

       1143
       +
       # Eio_main.run @@ fun _ ->

     

       1144
       +
         let c = make_cache fetch in

     

       1145
       +
         let test url =

     

       1146
       +
           traceln "Requesting %s..." url;

     

       1147
       +
           match c url with

     

       1148
       +
           | page -> traceln "%s -> %s" url page

     

       1149
       +
           | exception ex -> traceln "%s -> %a" url Fmt.exn ex

     

       1150
       +
         in

     

       1151
       +
         Fiber.List.iter test [

     

       1152
       +
           "http://example.com";

     

       1153
       +
           "http://example.com";

     

       1154
       +
           "http://bad.com";

     

       1155
       +
           "http://bad.com";

     

       1156
       +
         ];;

     

       1157
       +
       +Requesting http://example.com...

     

       1158
       +
       +Fetching "http://example.com"...

     

       1159
       +
       +Requesting http://example.com...

     

       1160
       +
       +Requesting http://bad.com...

     

       1161
       +
       +Fetching "http://bad.com"...

     

       1162
       +
       +Requesting http://bad.com...

     

       1163
       +
       +Got response for "http://example.com"

     

       1164
       +
       +http://example.com -> <h1>Example.com</h1>

     

       1165
       +
       +Got response for "http://bad.com"

     

       1166
       +
       +http://bad.com -> Failure("404 Not Found")

     

       1167
       +
       +http://example.com -> <h1>Example.com</h1>

     

       1168
       +
       +http://bad.com -> Failure("404 Not Found")

     

       1169
       +
       - : unit = ()

     

       1170
       +
       ```

     

       1171
       +
       

     

       1172
       +
       `Fiber.List.iter` is like `List.iter` but doesn't wait for each job to finish before starting the next.

     

       1173
       +
       Notice that we made four requests, but only started two download operations.

     

       1174
       +
       

     

       1175
       +
       This version of the cache remembers failed lookups too.

     

       1176
       +
       You could modify it to remove the entry on failure,

     

       1177
       +
       so that all clients currently waiting still fail,

     

       1178
       +
       but any future client asking for the failed resource will trigger a new download.

     

       1179
       +
       

     

       1180
       +
       This cache is not thread-safe.

     

       1181
       +
       You will need to add a mutex if you want to share it between domains.

     

       1182
       +
       

     

       1183
       +
       ### Streams

     

       1184
       +
       

     

       1185
       +
       A [stream][Eio.Stream] is a bounded queue. Reading from an empty stream waits until an item is available.

     

       1186
       +
       Writing to a full stream waits for space.

     

       1187
       +
       

     

       1188
       +
       ```ocaml

     

       1189
       +
       # Eio_main.run @@ fun _ ->

     

       1190
       +
         let stream = Eio.Stream.create 2 in

     

       1191
       +
         Fiber.both

     

       1192
       +
           (fun () ->

     

       1193
       +
              for i = 1 to 5 do

     

       1194
       +
                traceln "Adding %d..." i;

     

       1195
       +
                Eio.Stream.add stream i

     

       1196
       +
              done

     

       1197
       +
           )

     

       1198
       +
           (fun () ->

     

       1199
       +
              for i = 1 to 5 do

     

       1200
       +
                let x = Eio.Stream.take stream in

     

       1201
       +
                traceln "Got %d" x;

     

       1202
       +
                Fiber.yield ()

     

       1203
       +
              done

     

       1204
       +
           );;

     

       1205
       +
       +Adding 1...

     

       1206
       +
       +Adding 2...

     

       1207
       +
       +Adding 3...

     

       1208
       +
       +Got 1

     

       1209
       +
       +Adding 4...

     

       1210
       +
       +Got 2

     

       1211
       +
       +Adding 5...

     

       1212
       +
       +Got 3

     

       1213
       +
       +Got 4

     

       1214
       +
       +Got 5

     

       1215
       +
       - : unit = ()

     

       1216
       +
       ```

     

       1217
       +
       

     

       1218
       +
       Here, we create a stream with a maximum size of 2 items.

     

       1219
       +
       The first fiber added 1 and 2 to the stream, but had to wait before it could insert 3.

     

       1220
       +
       

     

       1221
       +
       A stream with a capacity of 1 acts like a mailbox.

     

       1222
       +
       A stream with a capacity of 0 will wait until both the sender and receiver are ready.

     

       1223
       +
       

     

       1224
       +
       Streams are thread-safe and can be used to communicate between domains.

     

       1225
       +
       

     

       1226
       +
       ### Example: Worker Pool

     

       1227
       +
       

     

       1228
       +
       A useful pattern is a pool of workers reading from a stream of work items.

     

       1229
       +
       Client fibers submit items to a stream and workers process the items:

     

       1230
       +
       

     

       1231
       +
       ```ocaml

     

       1232
       +
       let handle_job request =

     

       1233
       +
         Fiber.yield ();       (* (simulated work) *)

     

       1234
       +
         Printf.sprintf "Processed:%d" request

     

       1235
       +
       

     

       1236
       +
       let rec run_worker id stream =

     

       1237
       +
         let request, reply = Eio.Stream.take stream in

     

       1238
       +
         traceln "Worker %s processing request %d" id request;

     

       1239
       +
         Promise.resolve reply (handle_job request);

     

       1240
       +
         run_worker id stream

     

       1241
       +
       

     

       1242
       +
       let submit stream request =

     

       1243
       +
         let reply, resolve_reply = Promise.create () in

     

       1244
       +
         Eio.Stream.add stream (request, resolve_reply);

     

       1245
       +
         Promise.await reply

     

       1246
       +
       ```

     

       1247
       +
       

     

       1248
       +
       Each item in the stream is a request payload and a resolver for the reply promise.

     

       1249
       +
       

     

       1250
       +
       ```ocaml

     

       1251
       +
       # Eio_main.run @@ fun env ->

     

       1252
       +
         let domain_mgr = Eio.Stdenv.domain_mgr env in

     

       1253
       +
         Switch.run @@ fun sw ->

     

       1254
       +
         let stream = Eio.Stream.create 0 in

     

       1255
       +
         let spawn_worker name =

     

       1256
       +
           Fiber.fork_daemon ~sw (fun () ->

     

       1257
       +
              Eio.Domain_manager.run domain_mgr (fun () ->

     

       1258
       +
                 traceln "Worker %s ready" name;

     

       1259
       +
                 run_worker name stream

     

       1260
       +
              )

     

       1261
       +
           )

     

       1262
       +
         in

     

       1263
       +
         spawn_worker "A";

     

       1264
       +
         spawn_worker "B";

     

       1265
       +
         Switch.run (fun sw ->

     

       1266
       +
            for i = 1 to 3 do

     

       1267
       +
              Fiber.fork ~sw (fun () ->

     

       1268
       +
                traceln "Client %d submitting job..." i;

     

       1269
       +
                traceln "Client %d got %s" i (submit stream i)

     

       1270
       +
              );

     

       1271
       +
              Fiber.yield ()

     

       1272
       +
            done

     

       1273
       +
         );;

     

       1274
       +
       +Worker A ready

     

       1275
       +
       +Worker B ready

     

       1276
       +
       +Client 1 submitting job...

     

       1277
       +
       +Worker A processing request 1

     

       1278
       +
       +Client 2 submitting job...

     

       1279
       +
       +Worker B processing request 2

     

       1280
       +
       +Client 3 submitting job...

     

       1281
       +
       +Client 1 got Processed:1

     

       1282
       +
       +Worker A processing request 3

     

       1283
       +
       +Client 2 got Processed:2

     

       1284
       +
       +Client 3 got Processed:3

     

       1285
       +
       - : unit = ()

     

       1286
       +
       ```

     

       1287
       +
       

     

       1288
       +
       We use a zero-capacity stream here, which means that the `Stream.add` doesn't succeed until a worker accepts the job.

     

       1289
       +
       This is a good choice for a worker pool because it means that if the client fiber gets cancelled while waiting for a worker

     

       1290
       +
       then the job will never be run. It's also more efficient, as 0-capacity streams use a lock-free algorithm that is faster

     

       1291
       +
       when there are multiple domains.

     

       1292
       +
       Note that, while the stream itself is 0-capacity, clients still queue up waiting to use it.

     

       1293
       +
       

     

       1294
       +
       In the code above, any exception raised while processing a job will exit the whole program.

     

       1295
       +
       We might prefer to handle exceptions by sending them back to the client and continuing:

     

       1296
       +
       

     

       1297
       +
       ```ocaml

     

       1298
       +
       let rec run_worker id stream =

     

       1299
       +
         let request, reply = Eio.Stream.take stream in

     

       1300
       +
         traceln "Worker %s processing request %d" id request;

     

       1301
       +
         begin match handle_job request with

     

       1302
       +
           | result -> Promise.resolve_ok reply result

     

       1303
       +
           | exception ex -> Promise.resolve_error reply ex; Fiber.check ()

     

       1304
       +
         end;

     

       1305
       +
         run_worker id stream

     

       1306
       +
       ```

     

       1307
       +
       

     

       1308
       +
       The `Fiber.check ()` checks whether the worker itself has been cancelled, and exits the loop if so.

     

       1309
       +
       It's not actually necessary in this case,

     

       1310
       +
       because if we continue instead then the following `Stream.take` will perform the check anyway.

     

       1311
       +
       

     

       1312
       +
       Note: in a real system, you would probably use [Eio.Executor_pool][] for this rather than making your own pool.

     

       1313
       +
       

     

       1314
       +
       ### Mutexes and Semaphores

     

       1315
       +
       

     

       1316
       +
       Eio also provides `Mutex` and `Semaphore` sub-modules.

     

       1317
       +
       Each of these corresponds to the module with the same name in the OCaml standard library,

     

       1318
       +
       but allows other fibers to run while waiting instead of blocking the whole domain.

     

       1319
       +
       They are all safe to use in parallel from multiple domains.

     

       1320
       +
       

     

       1321
       +
       - [Eio.Mutex][] provides *mutual exclusion*, so that only one fiber can access a resource at a time.

     

       1322
       +
       - [Eio.Semaphore][] generalises this to allow up to *n* fibers to access a resource at once.

     

       1323
       +
       

     

       1324
       +
       For example, if we allow loading and saving data in a file there could be a problem

     

       1325
       +
       if we try to load the data while a save is in progress.

     

       1326
       +
       Protecting the file with a mutex will prevent that:

     

       1327
       +
       

     

       1328
       +
       ```ocaml

     

       1329
       +
       module Atomic_file = struct

     

       1330
       +
         type 'a t = {

     

       1331
       +
           path : 'a Eio.Path.t;

     

       1332
       +
           mutex : Eio.Mutex.t;

     

       1333
       +
         }

     

       1334
       +
       

     

       1335
       +
         let of_path path =

     

       1336
       +
           { path; mutex = Eio.Mutex.create () }

     

       1337
       +
       

     

       1338
       +
         let save t data =

     

       1339
       +
           Eio.Mutex.use_rw t.mutex ~protect:true (fun () ->

     

       1340
       +
              Eio.Path.save t.path data ~create:(`Or_truncate 0o644)

     

       1341
       +
           )

     

       1342
       +
       

     

       1343
       +
         let load t =

     

       1344
       +
           Eio.Mutex.use_ro t.mutex (fun () ->

     

       1345
       +
              Eio.Path.load t.path

     

       1346
       +
           )

     

       1347
       +
       end

     

       1348
       +
       ```

     

       1349
       +
       

     

       1350
       +
       The `~protect:true` in `save` makes the critical section non-cancellable,

     

       1351
       +
       so that if a cancel happens during a save then we will finish writing the data first.

     

       1352
       +
       It can be used like this:

     

       1353
       +
       

     

       1354
       +
       ```ocaml

     

       1355
       +
       # Eio_main.run @@ fun env ->

     

       1356
       +
         let dir = Eio.Stdenv.cwd env in

     

       1357
       +
         let t = Atomic_file.of_path (dir / "data") in

     

       1358
       +
         Fiber.both

     

       1359
       +
           (fun () -> Atomic_file.save t "some data")

     

       1360
       +
           (fun () ->

     

       1361
       +
             let data = Atomic_file.load t in

     

       1362
       +
             traceln "Loaded: %S" data

     

       1363
       +
           );;

     

       1364
       +
       +Loaded: "some data"

     

       1365
       +
       - : unit = ()

     

       1366
       +
       ```

     

       1367
       +
       

     

       1368
       +
       Note: In practice, a better way to make file writes atomic is

     

       1369
       +
       to write the data to a temporary file and then atomically rename it over the old data.

     

       1370
       +
       That will work even if the whole computer crashes, and does not delay cancellation.

     

       1371
       +
       

     

       1372
       +
       If the operation being performed is very fast (such as updating some in-memory counters),

     

       1373
       +
       then it is fine to use the standard library's `Mutex` instead.

     

       1374
       +
       

     

       1375
       +
       If the operation does not switch fibers *and* the resource is only accessed from one domain,

     

       1376
       +
       then no mutex is needed at all. For example:

     

       1377
       +
       

     

       1378
       +
       ```ocaml

     

       1379
       +
       (* No mutex needed if only used from a single domain: *)

     

       1380
       +
       

     

       1381
       +
       let in_use = ref 10

     

       1382
       +
       let free = ref 0

     

       1383
       +
       

     

       1384
       +
       let release () =

     

       1385
       +
         incr free;

     

       1386
       +
         decr in_use

     

       1387
       +
       ```

     

       1388
       +
       

     

       1389
       +
       ### Conditions

     

       1390
       +
       

     

       1391
       +
       [Eio.Condition][] allows a fiber to wait until some condition is true.

     

       1392
       +
       For example:

     

       1393
       +
       

     

       1394
       +
       ```ocaml

     

       1395
       +
       module X = struct

     

       1396
       +
         (* Note: this version is not safe to share across domains! *)

     

       1397
       +
       

     

       1398
       +
         type t = {

     

       1399
       +
           mutable x : int;

     

       1400
       +
           changed : Eio.Condition.t;

     

       1401
       +
         }

     

       1402
       +
       

     

       1403
       +
         let make x = { x; changed = Eio.Condition.create () }

     

       1404
       +
       

     

       1405
       +
         let await_zero t =

     

       1406
       +
           while t.x <> 0 do Eio.Condition.await_no_mutex t.changed done;

     

       1407
       +
           traceln "x is now zero"

     

       1408
       +
       

     

       1409
       +
         let set t x =

     

       1410
       +
           t.x <- x;

     

       1411
       +
           Eio.Condition.broadcast t.changed;

     

       1412
       +
           traceln "x set to %d" x

     

       1413
       +
       end

     

       1414
       +
       ```

     

       1415
       +
       

     

       1416
       +
       ```ocaml

     

       1417
       +
       # Eio_mock.Backend.run @@ fun () ->

     

       1418
       +
         let x = X.make 5 in

     

       1419
       +
         Fiber.both

     

       1420
       +
           (fun () ->

     

       1421
       +
              traceln "Waiting for x to be 0";

     

       1422
       +
              X.await_zero x

     

       1423
       +
           )

     

       1424
       +
           (fun () -> X.set x 0);;

     

       1425
       +
       +Waiting for x to be 0

     

       1426
       +
       +x set to 0

     

       1427
       +
       +x is now zero

     

       1428
       +
       - : unit = ()

     

       1429
       +
       ```

     

       1430
       +
       

     

       1431
       +
       Note that we need a loop in `await_zero`.

     

       1432
       +
       This is needed because it's possible that another fiber might set it to zero

     

       1433
       +
       and then set it to something else before the waiting fiber resumes.

     

       1434
       +
       

     

       1435
       +
       The above version is not safe to share across domains, because `await_zero` relies on the value of `x` not changing

     

       1436
       +
       after `x` is read but before `await_no_mutex` registers itself with the condition.

     

       1437
       +
       Here's a domain-safe version:

     

       1438
       +
       

     

       1439
       +
       ```ocaml

     

       1440
       +
       module Y = struct

     

       1441
       +
         (* Safe to share between domains. *)

     

       1442
       +
       

     

       1443
       +
         type t = {

     

       1444
       +
           mutable y : int;

     

       1445
       +
           mutex : Eio.Mutex.t;

     

       1446
       +
           changed : Eio.Condition.t;

     

       1447
       +
         }

     

       1448
       +
       

     

       1449
       +
         let make y = {

     

       1450
       +
           y;

     

       1451
       +
           mutex = Eio.Mutex.create ();

     

       1452
       +
           changed = Eio.Condition.create ();

     

       1453
       +
         }

     

       1454
       +
       

     

       1455
       +
         let await_zero t =

     

       1456
       +
           Eio.Mutex.use_ro t.mutex (fun () ->

     

       1457
       +
             while t.y <> 0 do Eio.Condition.await t.changed t.mutex done;

     

       1458
       +
             traceln "y is now zero (at least until we release the mutex)"

     

       1459
       +
           )

     

       1460
       +
       

     

       1461
       +
         let set t y =

     

       1462
       +
           Eio.Mutex.use_rw t.mutex ~protect:true (fun () ->

     

       1463
       +
              t.y <- y;

     

       1464
       +
              Eio.Condition.broadcast t.changed;

     

       1465
       +
              traceln "y set to %d" y

     

       1466
       +
           );

     

       1467
       +
       end

     

       1468
       +
       ```

     

       1469
       +
       

     

       1470
       +
       Here, `Eio.Condition.await` registers itself with `changed` and only then releases the mutex,

     

       1471
       +
       allowing other threads to change `y`. When it gets woken, it re-acquires the mutex.

     

       1472
       +
       

     

       1473
       +
       ```ocaml

     

       1474
       +
       # Eio_mock.Backend.run @@ fun () ->

     

       1475
       +
         let y = Y.make 5 in

     

       1476
       +
         Fiber.both

     

       1477
       +
           (fun () ->

     

       1478
       +
              traceln "Waiting for y to be 0";

     

       1479
       +
              Y.await_zero y

     

       1480
       +
           )

     

       1481
       +
           (fun () -> Y.set y 0);;

     

       1482
       +
       +Waiting for y to be 0

     

       1483
       +
       +y set to 0

     

       1484
       +
       +y is now zero (at least until we release the mutex)

     

       1485
       +
       - : unit = ()

     

       1486
       +
       ```

     

       1487
       +
       

     

       1488
       +
       Conditions are more difficult to use correctly than e.g. promises or streams.

     

       1489
       +
       In particular, it is easy to miss a notification due to `broadcast` getting called before `await`.

     

       1490
       +
       However, they can be useful if used carefully.

     

       1491
       +
       

     

       1492
       +
       ### Example: Signal handlers

     

       1493
       +
       

     

       1494
       +
       On Unix-type systems, processes can react to *signals*.

     

       1495
       +
       For example, pressing Ctrl-C will send the `SIGINT` (interrupt) signal.

     

       1496
       +
       

     

       1497
       +
       Here is an example function that allows itself to be interrupted:

     

       1498
       +
       

     

       1499
       +
       ```ocaml

     

       1500
       +
       let run_op ~interrupted =

     

       1501
       +
         Fiber.first

     

       1502
       +
           (fun () ->

     

       1503
       +
              Eio.Condition.await_no_mutex interrupted;

     

       1504
       +
              traceln "Cancelled at user's request."

     

       1505
       +
           )

     

       1506
       +
           (fun () ->

     

       1507
       +
              traceln "Running operation (Ctrl-C to cancel)...";

     

       1508
       +
              Fiber.await_cancel ()       (* Simulated work *)

     

       1509
       +
           )

     

       1510
       +
       ```

     

       1511
       +
       

     

       1512
       +
       Note that we don't need a mutex here.

     

       1513
       +
       We're just waiting for the number of interrupts received to change,

     

       1514
       +
       and, since that increases monotonically, once we get woken we always want to continue.

     

       1515
       +
       Also, we don't care about missing interrupts from before this operation started.

     

       1516
       +
       

     

       1517
       +
       The code here is quite subtle.

     

       1518
       +
       We rely on the fact that the first branch of the `Fiber.first` runs first,

     

       1519
       +
       and only starts running the second branch once `await_no_mutex` has finished registering.

     

       1520
       +
       Thus, we never display the message telling the user to press Ctrl-C before we're ready

     

       1521
       +
       to receive it.

     

       1522
       +
       This isn't likely to matter if a human is responding to the message,

     

       1523
       +
       but if the response is automated then the delay could matter.

     

       1524
       +
       

     

       1525
       +
       To run this function, we need to install a signal handler.

     

       1526
       +
       There are very few things that you can do safely in a signal handler.

     

       1527
       +
       For example, you can't take a mutex in a signal handler

     

       1528
       +
       because the signal might have interrupted a fiber that had already locked it.

     

       1529
       +
       However, you can safely call `Eio.Condition.broadcast`:

     

       1530
       +
       

     

       1531
       +
       <!-- $MDX non-deterministic=command -->

     

       1532
       +
       ```ocaml

     

       1533
       +
       # Eio_main.run @@ fun _env ->

     

       1534
       +
         let interrupted = Eio.Condition.create () in

     

       1535
       +
         let handle_signal (_signum : int) =

     

       1536
       +
           (* Warning: we're in a signal handler now.

     

       1537
       +
              Most operations are unsafe here, except for Eio.Condition.broadcast! *)

     

       1538
       +
           Eio.Condition.broadcast interrupted

     

       1539
       +
         in

     

       1540
       +
         Sys.set_signal Sys.sigint (Signal_handle handle_signal);

     

       1541
       +
         run_op ~interrupted;;

     

       1542
       +
       +Running operation (Ctrl-C to cancel)...

     

       1543
       +
       [ user presses Ctrl-C here ]

     

       1544
       +
       +Cancelled at user's request.

     

       1545
       +
       - : unit = ()

     

       1546
       +
       ```

     

       1547
       +
       

     

       1548
       +
       Another common pattern when using signals is using `SIGHUP`

     

       1549
       +
       to tell an application to reload its configuration file:

     

       1550
       +
       

     

       1551
       +
       <!-- $MDX file=examples/signals/main.ml,part=main -->

     

       1552
       +
       ```ocaml

     

       1553
       +
       let main ~config_changed =

     

       1554
       +
         Eio.Condition.loop_no_mutex config_changed (fun () ->

     

       1555
       +
             traceln "Reading configuration ('kill -SIGHUP %d' to reload)..." (Unix.getpid ());

     

       1556
       +
             load_config ();

     

       1557
       +
             traceln "Finished reading configuration";

     

       1558
       +
             None      (* Keep waiting for futher changes *)

     

       1559
       +
           )

     

       1560
       +
       ```

     

       1561
       +
       

     

       1562
       +
       See the `examples/signals` directory for the full code.

     

       1563
       +
       

     

       1564
       +
       ## Design Note: Determinism

     

       1565
       +
       

     

       1566
       +
       Within a domain, fibers are scheduled deterministically.

     

       1567
       +
       Programs using only the Eio APIs can only behave non-deterministically if given a capability to do so from somewhere else.

     

       1568
       +
       

     

       1569
       +
       For example, `Fiber.both f g` always starts running `f` first,

     

       1570
       +
       and only switches to `g` when `f` finishes or performs an effect that can switch fibers.

     

       1571
       +
       

     

       1572
       +
       Performing IO with external objects (e.g., `stdout`, files, or network sockets) will introduce non-determinism,

     

       1573
       +
       as will using multiple domains.

     

       1574
       +
       

     

       1575
       +
       Note that `traceln` is unusual. Although it writes (by default) to stderr, it will not switch fibers.

     

       1576
       +
       Instead, if the OS is not ready to receive trace output, the whole domain is paused until it is ready.

     

       1577
       +
       This means that adding `traceln` to deterministic code will not affect its scheduling.

     

       1578
       +
       

     

       1579
       +
       In particular, if you test your code by providing (deterministic) mocks then the tests will be deterministic.

     

       1580
       +
       An easy way to write tests is by having the mocks call `traceln` and then comparing the trace output with the expected output.

     

       1581
       +
       See Eio's own tests for examples, e.g., [tests/switch.md](tests/switch.md).

     

       1582
       +
       

     

       1583
       +
       Note: this only applies to the high-level APIs in the `Eio` module.

     

       1584
       +
       Programs can behave non-deterministically when using `Eio_unix` or the various `Low_level` APIs provided by the backends.

     

       1585
       +
       

     

       1586
       +
       ## Provider Interfaces

     

       1587
       +
       

     

       1588
       +
       Eio applications use resources by calling functions (such as `Eio.Flow.write`).

     

       1589
       +
       These functions are actually wrappers that look up the implementing module and call

     

       1590
       +
       the appropriate function on that.

     

       1591
       +
       This allows you to define your own resources.

     

       1592
       +
       

     

       1593
       +
       Here's a flow that produces an endless stream of zeros (like "/dev/zero"):

     

       1594
       +
       

     

       1595
       +
       ```ocaml

     

       1596
       +
       module Zero = struct

     

       1597
       +
         type t = unit

     

       1598
       +
       

     

       1599
       +
         let single_read () buf = 

     

       1600
       +
           Cstruct.memset buf 0;

     

       1601
       +
           Cstruct.length buf

     

       1602
       +
       

     

       1603
       +
         let read_methods = []         (* Optional optimisations *)

     

       1604
       +
       end

     

       1605
       +
       

     

       1606
       +
       let ops = Eio.Flow.Pi.source (module Zero)

     

       1607
       +
       

     

       1608
       +
       let zero = Eio.Resource.T ((), ops)

     

       1609
       +
       ```

     

       1610
       +
       

     

       1611
       +
       It can then be used like any other Eio flow:

     

       1612
       +
       

     

       1613
       +
       ```ocaml

     

       1614
       +
       # Eio_main.run @@ fun _ ->

     

       1615
       +
         let r = Eio.Buf_read.of_flow zero ~max_size:100 in

     

       1616
       +
         traceln "Got: %S" (Eio.Buf_read.take 4 r);;

     

       1617
       +
       +Got: "\000\000\000\000"

     

       1618
       +
       - : unit = ()

     

       1619
       +
       ```

     

       1620
       +
       

     

       1621
       +
       ## Example Applications

     

       1622
       +
       

     

       1623
       +
       - [gemini-eio][] is a simple Gemini browser. It shows how to integrate Eio with `ocaml-tls` and `notty`.

     

       1624
       +
       - [cohttp-eio/examples](https://github.com/mirage/ocaml-cohttp/tree/master/cohttp-eio/examples) shows how to use Eio with HTTP.

     

       1625
       +
       - [capnp-rpc](https://github.com/mirage/capnp-rpc) shows how to use Eio with Cap'n Proto.

     

       1626
       +
       - [Awesome Multicore OCaml][] lists many other projects.

     

       1627
       +
       

     

       1628
       +
       ## Integrations

     

       1629
       +
       

     

       1630
       +
       Eio can be used with several other IO libraries.

     

       1631
       +
       

     

       1632
       +
       ### Async

     

       1633
       +
       

     

       1634
       +
       [Async_eio][] has experimental support for running Async and Eio code together in a single domain.

     

       1635
       +
       

     

       1636
       +
       ### Lwt

     

       1637
       +
       

     

       1638
       +
       You can use [Lwt_eio][] to run Lwt threads and Eio fibers together in a single domain,

     

       1639
       +
       and to convert between Lwt and Eio promises.

     

       1640
       +
       This may be useful during the process of porting existing code to Eio.

     

       1641
       +
       

     

       1642
       +
       ### Unix and System Threads

     

       1643
       +
       

     

       1644
       +
       The [Eio_unix][] module provides features for using Eio with OCaml's Unix module.

     

       1645
       +
       In particular, `Eio_unix.run_in_systhread` can be used to run a blocking operation in a separate systhread,

     

       1646
       +
       allowing it to be used within Eio without blocking the whole domain.

     

       1647
       +
       

     

       1648
       +
       ### Domainslib

     

       1649
       +
       

     

       1650
       +
       For certain compute-intensive tasks it may be useful to send work to a pool of [Domainslib][] worker domains.

     

       1651
       +
       You can resolve an Eio promise from non-Eio domains (or systhreads), which provides an easy way to retrieve the result.

     

       1652
       +
       For example:

     

       1653
       +
       

     

       1654
       +
       <!-- $MDX skip -->

     

       1655
       +
       ```ocaml

     

       1656
       +
       open Eio.Std

     

       1657
       +
       

     

       1658
       +
       let pool = Domainslib.Task.setup_pool ~num_domains:2 ()

     

       1659
       +
       

     

       1660
       +
       let fib n = ... (* Some Domainslib function *)

     

       1661
       +
       

     

       1662
       +
       let run_in_pool fn x =

     

       1663
       +
         let result, set_result = Promise.create () in

     

       1664
       +
         let _ : unit Domainslib.Task.promise = Domainslib.Task.async pool (fun () ->

     

       1665
       +
             Promise.resolve set_result @@

     

       1666
       +
             match fn x with

     

       1667
       +
             | r -> Ok r

     

       1668
       +
             | exception ex -> Error ex

     

       1669
       +
           )

     

       1670
       +
         in

     

       1671
       +
         Promise.await_exn result

     

       1672
       +
       

     

       1673
       +
       let () =

     

       1674
       +
         Eio_main.run @@ fun _ ->

     

       1675
       +
         Fiber.both

     

       1676
       +
           (fun () -> traceln "fib 30 = %d" (run_in_pool fib 30))

     

       1677
       +
           (fun () -> traceln "fib 10 = %d" (run_in_pool fib 10))

     

       1678
       +
       ```

     

       1679
       +
       

     

       1680
       +
       Note that most Domainslib functions can only be called from code running in the Domainslib pool,

     

       1681
       +
       while most Eio functions can only be used from Eio domains.

     

       1682
       +
       The bridge function `run_in_pool` makes use of the fact that `Domainslib.Task.async` is able to run from

     

       1683
       +
       an Eio domain, and `Eio.Promise.resolve` is able to run from a Domainslib one.

     

       1684
       +
       

     

       1685
       +
       ### kcas

     

       1686
       +
       

     

       1687
       +
       Eio provides the support [kcas][] requires to implement blocking in the

     

       1688
       +
       lock-free software transactional memory (STM) implementation that it provides.

     

       1689
       +
       This means that one can use all the composable lock-free data structures and

     

       1690
       +
       primitives for communication and synchronization implemented using **kcas** to

     

       1691
       +
       communicate and synchronize between Eio fibers, raw domains, and any other

     

       1692
       +
       schedulers that provide the domain local await mechanism.

     

       1693
       +
       

     

       1694
       +
       To demonstrate **kcas**

     

       1695
       +
       

     

       1696
       +
       ```ocaml

     

       1697
       +
       # #require "kcas"

     

       1698
       +
       # open Kcas

     

       1699
       +
       ```

     

       1700
       +
       

     

       1701
       +
       let's first create a couple of shared memory locations

     

       1702
       +
       

     

       1703
       +
       ```ocaml

     

       1704
       +
       let x = Loc.make 0

     

       1705
       +
       let y = Loc.make 0

     

       1706
       +
       ```

     

       1707
       +
       

     

       1708
       +
       and spawn a domain

     

       1709
       +
       

     

       1710
       +
       ```ocaml

     

       1711
       +
       # let foreign_domain = Domain.spawn @@ fun () ->

     

       1712
       +
           let x = Loc.get_as (fun x -> Retry.unless (x <> 0); x) x in

     

       1713
       +
           Loc.set y 22;

     

       1714
       +
           x

     

       1715
       +
       val foreign_domain : int Domain.t = <abstr>

     

       1716
       +
       ```

     

       1717
       +
       

     

       1718
       +
       that first waits for one of the locations to change value and then writes to the

     

       1719
       +
       other location.

     

       1720
       +
       

     

       1721
       +
       Then we run a Eio program

     

       1722
       +
       

     

       1723
       +
       ```ocaml

     

       1724
       +
       # let y = Eio_main.run @@ fun _env ->

     

       1725
       +
           Loc.set x 20;

     

       1726
       +
           Loc.get_as (fun y -> Retry.unless (y <> 0); y) y

     

       1727
       +
       val y : int = 22

     

       1728
       +
       ```

     

       1729
       +
       

     

       1730
       +
       that first writes to the location the other domain is waiting on and then waits

     

       1731
       +
       for the other domain to write to the other location.

     

       1732
       +
       

     

       1733
       +
       Joining with the other domain

     

       1734
       +
       

     

       1735
       +
       ```ocaml

     

       1736
       +
       # y + Domain.join foreign_domain

     

       1737
       +
       - : int = 42

     

       1738
       +
       ```

     

       1739
       +
       

     

       1740
       +
       we arrive at the answer.

     

       1741
       +
       

     

       1742
       +
       ## Best Practices

     

       1743
       +
       

     

       1744
       +
       This section contains some recommendations for designing library APIs for use with Eio.

     

       1745
       +
       

     

       1746
       +
       ### Switches

     

       1747
       +
       

     

       1748
       +
       A function should not take a switch argument if it could create one internally instead.

     

       1749
       +
       

     

       1750
       +
       Taking a switch indicates that a function creates resources that outlive the function call,

     

       1751
       +
       and users seeing a switch argument will naturally wonder what these resources may be

     

       1752
       +
       and what lifetime to give them, which is confusing if this is not needed.

     

       1753
       +
       

     

       1754
       +
       Creating the switch inside your function ensures that all resources are released

     

       1755
       +
       promptly.

     

       1756
       +
       

     

       1757
       +
       ```ocaml

     

       1758
       +
       (* BAD - switch should be created internally instead *)

     

       1759
       +
       let load_config ~sw path =

     

       1760
       +
         parse_config (Eio.Path.open_in ~sw path)

     

       1761
       +
       

     

       1762
       +
       (* GOOD - less confusing and closes file promptly *)

     

       1763
       +
       let load_config path =

     

       1764
       +
         Switch.run @@ fun sw ->

     

       1765
       +
         parse_config (Eio.Path.open_in ~sw path)

     

       1766
       +
       ```

     

       1767
       +
       

     

       1768
       +
       Of course, you could use `with_open_in` in this case to simplify it further.

     

       1769
       +
       

     

       1770
       +
       ### Casting

     

       1771
       +
       

     

       1772
       +
       Unlike many languages, OCaml does not automatically cast to super-types as needed.

     

       1773
       +
       Remember to keep the type polymorphic in your interface so users don't need to do this manually.

     

       1774
       +
       

     

       1775
       +
       For example, if you need an `Eio.Flow.source` then users should be able to use a `Flow.two_way`

     

       1776
       +
       without having to cast it first:

     

       1777
       +
       

     

       1778
       +
       <!-- $MDX skip -->

     

       1779
       +
       ```ocaml

     

       1780
       +
       (* BAD - user must cast to use function: *)

     

       1781
       +
       module Message : sig

     

       1782
       +
         type t

     

       1783
       +
         val read : Eio.Flow.source_ty r -> t

     

       1784
       +
       end

     

       1785
       +
       

     

       1786
       +
       (* GOOD - a Flow.two_way can be used without casting: *)

     

       1787
       +
       module Message : sig

     

       1788
       +
         type t

     

       1789
       +
         val read : _ Eio.Flow.source -> t

     

       1790
       +
       end

     

       1791
       +
       ```

     

       1792
       +
       

     

       1793
       +
       If you want to store the argument, this may require you to cast internally:

     

       1794
       +
       

     

       1795
       +
       ```ocaml

     

       1796
       +
       module Foo : sig

     

       1797
       +
         type t

     

       1798
       +
         val of_source : _ Eio.Flow.source -> t

     

       1799
       +
       end = struct

     

       1800
       +
         type t = {

     

       1801
       +
           src : Eio.Flow.source_ty r;

     

       1802
       +
         }

     

       1803
       +
       

     

       1804
       +
         let of_source x = {

     

       1805
       +
           src = (x :> Eio.Flow.source_ty r);

     

       1806
       +
         }

     

       1807
       +
       end

     

       1808
       +
       ```

     

       1809
       +
       

     

       1810
       +
       ### Passing env

     

       1811
       +
       

     

       1812
       +
       The `env` value you get from `Eio_main.run` is a powerful capability,

     

       1813
       +
       and programs are easier to understand when it's not passed around too much.

     

       1814
       +
       

     

       1815
       +
       In many cases, it's clearer (if a little more verbose) to take the resources you need as separate arguments, e.g.

     

       1816
       +
       

     

       1817
       +
       <!-- $MDX skip -->

     

       1818
       +
       ```ocaml

     

       1819
       +
       module Status : sig

     

       1820
       +
         val check :

     

       1821
       +
           clock:_ Eio.Time.clock ->

     

       1822
       +
           net:_ Eio.Net.t ->

     

       1823
       +
           bool

     

       1824
       +
       end

     

       1825
       +
       ```

     

       1826
       +
       

     

       1827
       +
       You can also provide a convenience function that takes an `env` too.

     

       1828
       +
       Doing this is most appropriate if many resources are needed and

     

       1829
       +
       your library is likely to be initialised right at the start of the user's application.

     

       1830
       +
       

     

       1831
       +
       In that case, be sure to request only the resources you need, rather than the full set.

     

       1832
       +
       This makes it clearer what you library does, makes it easier to test,

     

       1833
       +
       and allows it to be used on platforms without the full set of OS resources.

     

       1834
       +
       If you define the type explicitly, you can describe why you need each resource there:

     

       1835
       +
       

     

       1836
       +
       <!-- $MDX skip -->

     

       1837
       +
       ```ocaml

     

       1838
       +
       module Status : sig

     

       1839
       +
         type 'a env = 'a constraint 'a = <

     

       1840
       +
           net : _ Eio.Net.t;             (** To connect to the servers *)

     

       1841
       +
           clock : _ Eio.Time.clock;      (** Needed for timeouts *)

     

       1842
       +
           ..

     

       1843
       +
         > as 'a

     

       1844
       +
       

     

       1845
       +
         val check : _ env -> bool

     

       1846
       +
       end

     

       1847
       +
       ```

     

       1848
       +
       

     

       1849
       +
       ## Further Reading

     

       1850
       +
       

     

       1851
       +
       - [API reference][Eio API]

     

       1852
       +
       - [doc/rationale.md](doc/rationale.md) describes some of Eio's design tradeoffs in more detail.

     

       1853
       +
       - [HACKING.md](./HACKING.md) describes how to work with the Eio source code.

     

       1854
       +
       

     

       1855
       +
       Some background about the effects system can be found in:

     

       1856
       +
       

     

       1857
       +
       - [Experiences with effects (video)](https://watch.ocaml.org/videos/watch/74ece0a8-380f-4e2a-bef5-c6bb9092be89), OCaml Workshop 2021.

     

       1858
       +
       - ["Retrofitting Concurrency onto OCaml"](https://kcsrk.info/papers/retro-concurrency_pldi_21.pdf) (to appear, PLDI 2021)

     

       1859
       +
       - https://kcsrk.info/ocaml/multicore/2015/05/20/effects-multicore/

     

       1860
       +
       - Effects examples: https://github.com/ocaml-multicore/effects-examples/tree/master/aio

     

       1861
       +
       - [Concurrent System Programming with Effect Handlers](https://www.repository.cam.ac.uk/bitstream/handle/1810/283239/paper.pdf?sequence=3&isAllowed=y)

     

       1862
       +
       - [Asynchronous effect based IO using effect handlers](https://github.com/kayceesrk/ocaml-aeio)

     

       1863
       +
       

     

       1864
       +
       [Eio API]: https://ocaml-multicore.github.io/eio/

     

       1865
       +
       [Lwt_eio]: https://github.com/ocaml-multicore/lwt_eio

     

       1866
       +
       [mirage-trace-viewer]: https://github.com/talex5/mirage-trace-viewer

     

       1867
       +
       [structured concurrency]: https://en.wikipedia.org/wiki/Structured_concurrency

     

       1868
       +
       [gemini-eio]: https://gitlab.com/talex5/gemini-eio

     

       1869
       +
       [Awesome Multicore OCaml]: https://github.com/ocaml-multicore/awesome-multicore-ocaml

     

       1870
       +
       [Eio]: https://ocaml-multicore.github.io/eio/eio/Eio/index.html

     

       1871
       +
       [Eio.Std]: https://ocaml-multicore.github.io/eio/eio/Eio/Std/index.html

     

       1872
       +
       [Eio.Fiber]: https://ocaml-multicore.github.io/eio/eio/Eio/Fiber/index.html

     

       1873
       +
       [Eio.Flow]: https://ocaml-multicore.github.io/eio/eio/Eio/Flow/index.html

     

       1874
       +
       [Eio.Cancel]: https://ocaml-multicore.github.io/eio/eio/Eio/Cancel/index.html

     

       1875
       +
       [Eio.Switch]: https://ocaml-multicore.github.io/eio/eio/Eio/Switch/index.html

     

       1876
       +
       [Eio.Net]: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

     

       1877
       +
       [Eio.Buf_read]: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_read/index.html

     

       1878
       +
       [Eio.Buf_write]: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_write/index.html

     

       1879
       +
       [Eio.Path]: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

     

       1880
       +
       [Eio.Time]: https://ocaml-multicore.github.io/eio/eio/Eio/Time/index.html

     

       1881
       +
       [Eio.Domain_manager]: https://ocaml-multicore.github.io/eio/eio/Eio/Domain_manager/index.html

     

       1882
       +
       [Eio.Executor_pool]: https://ocaml-multicore.github.io/eio/eio/Eio/Executor_pool/index.html

     

       1883
       +
       [Eio.Promise]: https://ocaml-multicore.github.io/eio/eio/Eio/Promise/index.html

     

       1884
       +
       [Eio.Stream]: https://ocaml-multicore.github.io/eio/eio/Eio/Stream/index.html

     

       1885
       +
       [Eio_posix]: https://ocaml-multicore.github.io/eio/eio_posix/Eio_posix/index.html

     

       1886
       +
       [Eio_linux]: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/index.html

     

       1887
       +
       [Eio_windows]: https://github.com/ocaml-multicore/eio/blob/main/lib_eio_windows/eio_windows.mli

     

       1888
       +
       [Eio_main]: https://ocaml-multicore.github.io/eio/eio_main/Eio_main/index.html

     

       1889
       +
       [Eio.traceln]: https://ocaml-multicore.github.io/eio/eio/Eio/index.html#val-traceln

     

       1890
       +
       [Eio_main.run]: https://ocaml-multicore.github.io/eio/eio_main/Eio_main/index.html#val-run

     

       1891
       +
       [Eio_mock]: https://ocaml-multicore.github.io/eio/eio/Eio_mock/index.html

     

       1892
       +
       [Eio_unix]: https://ocaml-multicore.github.io/eio/eio/Eio_unix/index.html

     

       1893
       +
       [Async_eio]: https://github.com/talex5/async_eio

     

       1894
       +
       [Eio.Mutex]: https://ocaml-multicore.github.io/eio/eio/Eio/Mutex/index.html

     

       1895
       +
       [Eio.Semaphore]: https://ocaml-multicore.github.io/eio/eio/Eio/Semaphore/index.html

     

       1896
       +
       [Eio.Condition]: https://ocaml-multicore.github.io/eio/eio/Eio/Condition/index.html

     

       1897
       +
       [Domainslib]: https://github.com/ocaml-multicore/domainslib

     

       1898
       +
       [kcas]: https://github.com/ocaml-multicore/kcas

     

       1899
       +
       [Lambda Capabilities]: https://roscidus.com/blog/blog/2023/04/26/lambda-capabilities/

     

       1900
       +
       [Eio.Process]: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html

     

       1901
       +
       [Dev meetings]: https://docs.google.com/document/d/1ZBfbjAkvEkv9ldumpZV5VXrEc_HpPeYjHPW_TiwJe4Q

     

       1902
       +
       [Olly]: https://github.com/tarides/runtime_events_tools

     

       1903
       +
       [eio-trace]: https://github.com/ocaml-multicore/eio-trace

     

       1904
       +
       [cap_enter]: https://man.freebsd.org/cgi/man.cgi?query=cap_enter

     

       1905
       +
       [eio_js]: https://github.com/ocaml-multicore/eio_js

+277

spec/fcgi.go

···

       1
       +
       // Copyright 2011 The Go Authors. All rights reserved.

     

       2
       +
       // Use of this source code is governed by a BSD-style

     

       3
       +
       // license that can be found in the LICENSE file.

     

       4
       +
       

     

       5
       +
       // Package fcgi implements the FastCGI protocol.

     

       6
       +
       //

     

       7
       +
       // See https://fast-cgi.github.io/ for an unofficial mirror of the

     

       8
       +
       // original documentation.

     

       9
       +
       //

     

       10
       +
       // Currently only the responder role is supported.

     

       11
       +
       package fcgi

     

       12
       +
       

     

       13
       +
       // This file defines the raw protocol and some utilities used by the child and

     

       14
       +
       // the host.

     

       15
       +
       

     

       16
       +
       import (

     

       17
       +
       	"bufio"

     

       18
       +
       	"bytes"

     

       19
       +
       	"encoding/binary"

     

       20
       +
       	"errors"

     

       21
       +
       	"io"

     

       22
       +
       	"sync"

     

       23
       +
       )

     

       24
       +
       

     

       25
       +
       // recType is a record type, as defined by

     

       26
       +
       // https://web.archive.org/web/20150420080736/http://www.fastcgi.com/drupal/node/6?q=node/22#S8

     

       27
       +
       type recType uint8

     

       28
       +
       

     

       29
       +
       const (

     

       30
       +
       	typeBeginRequest    recType = 1

     

       31
       +
       	typeAbortRequest    recType = 2

     

       32
       +
       	typeEndRequest      recType = 3

     

       33
       +
       	typeParams          recType = 4

     

       34
       +
       	typeStdin           recType = 5

     

       35
       +
       	typeStdout          recType = 6

     

       36
       +
       	typeStderr          recType = 7

     

       37
       +
       	typeData            recType = 8

     

       38
       +
       	typeGetValues       recType = 9

     

       39
       +
       	typeGetValuesResult recType = 10

     

       40
       +
       	typeUnknownType     recType = 11

     

       41
       +
       )

     

       42
       +
       

     

       43
       +
       // keep the connection between web-server and responder open after request

     

       44
       +
       const flagKeepConn = 1

     

       45
       +
       

     

       46
       +
       const (

     

       47
       +
       	maxWrite = 65535 // maximum record body

     

       48
       +
       	maxPad   = 255

     

       49
       +
       )

     

       50
       +
       

     

       51
       +
       const (

     

       52
       +
       	roleResponder = iota + 1 // only Responders are implemented.

     

       53
       +
       	roleAuthorizer

     

       54
       +
       	roleFilter

     

       55
       +
       )

     

       56
       +
       

     

       57
       +
       const (

     

       58
       +
       	statusRequestComplete = iota

     

       59
       +
       	statusCantMultiplex

     

       60
       +
       	statusOverloaded

     

       61
       +
       	statusUnknownRole

     

       62
       +
       )

     

       63
       +
       

     

       64
       +
       type header struct {

     

       65
       +
       	Version       uint8

     

       66
       +
       	Type          recType

     

       67
       +
       	Id            uint16

     

       68
       +
       	ContentLength uint16

     

       69
       +
       	PaddingLength uint8

     

       70
       +
       	Reserved      uint8

     

       71
       +
       }

     

       72
       +
       

     

       73
       +
       type beginRequest struct {

     

       74
       +
       	role     uint16

     

       75
       +
       	flags    uint8

     

       76
       +
       	reserved [5]uint8

     

       77
       +
       }

     

       78
       +
       

     

       79
       +
       func (br *beginRequest) read(content []byte) error {

     

       80
       +
       	if len(content) != 8 {

     

       81
       +
       		return errors.New("fcgi: invalid begin request record")

     

       82
       +
       	}

     

       83
       +
       	br.role = binary.BigEndian.Uint16(content)

     

       84
       +
       	br.flags = content[2]

     

       85
       +
       	return nil

     

       86
       +
       }

     

       87
       +
       

     

       88
       +
       // for padding so we don't have to allocate all the time

     

       89
       +
       // not synchronized because we don't care what the contents are

     

       90
       +
       var pad [maxPad]byte

     

       91
       +
       

     

       92
       +
       func (h *header) init(recType recType, reqId uint16, contentLength int) {

     

       93
       +
       	h.Version = 1

     

       94
       +
       	h.Type = recType

     

       95
       +
       	h.Id = reqId

     

       96
       +
       	h.ContentLength = uint16(contentLength)

     

       97
       +
       	h.PaddingLength = uint8(-contentLength & 7)

     

       98
       +
       }

     

       99
       +
       

     

       100
       +
       // conn sends records over rwc

     

       101
       +
       type conn struct {

     

       102
       +
       	mutex    sync.Mutex

     

       103
       +
       	rwc      io.ReadWriteCloser

     

       104
       +
       	closeErr error

     

       105
       +
       	closed   bool

     

       106
       +
       

     

       107
       +
       	// to avoid allocations

     

       108
       +
       	buf bytes.Buffer

     

       109
       +
       	h   header

     

       110
       +
       }

     

       111
       +
       

     

       112
       +
       func newConn(rwc io.ReadWriteCloser) *conn {

     

       113
       +
       	return &conn{rwc: rwc}

     

       114
       +
       }

     

       115
       +
       

     

       116
       +
       // Close closes the conn if it is not already closed.

     

       117
       +
       func (c *conn) Close() error {

     

       118
       +
       	c.mutex.Lock()

     

       119
       +
       	defer c.mutex.Unlock()

     

       120
       +
       	if !c.closed {

     

       121
       +
       		c.closeErr = c.rwc.Close()

     

       122
       +
       		c.closed = true

     

       123
       +
       	}

     

       124
       +
       	return c.closeErr

     

       125
       +
       }

     

       126
       +
       

     

       127
       +
       type record struct {

     

       128
       +
       	h   header

     

       129
       +
       	buf [maxWrite + maxPad]byte

     

       130
       +
       }

     

       131
       +
       

     

       132
       +
       func (rec *record) read(r io.Reader) (err error) {

     

       133
       +
       	if err = binary.Read(r, binary.BigEndian, &rec.h); err != nil {

     

       134
       +
       		return err

     

       135
       +
       	}

     

       136
       +
       	if rec.h.Version != 1 {

     

       137
       +
       		return errors.New("fcgi: invalid header version")

     

       138
       +
       	}

     

       139
       +
       	n := int(rec.h.ContentLength) + int(rec.h.PaddingLength)

     

       140
       +
       	if _, err = io.ReadFull(r, rec.buf[:n]); err != nil {

     

       141
       +
       		return err

     

       142
       +
       	}

     

       143
       +
       	return nil

     

       144
       +
       }

     

       145
       +
       

     

       146
       +
       func (r *record) content() []byte {

     

       147
       +
       	return r.buf[:r.h.ContentLength]

     

       148
       +
       }

     

       149
       +
       

     

       150
       +
       // writeRecord writes and sends a single record.

     

       151
       +
       func (c *conn) writeRecord(recType recType, reqId uint16, b []byte) error {

     

       152
       +
       	c.mutex.Lock()

     

       153
       +
       	defer c.mutex.Unlock()

     

       154
       +
       	c.buf.Reset()

     

       155
       +
       	c.h.init(recType, reqId, len(b))

     

       156
       +
       	if err := binary.Write(&c.buf, binary.BigEndian, c.h); err != nil {

     

       157
       +
       		return err

     

       158
       +
       	}

     

       159
       +
       	if _, err := c.buf.Write(b); err != nil {

     

       160
       +
       		return err

     

       161
       +
       	}

     

       162
       +
       	if _, err := c.buf.Write(pad[:c.h.PaddingLength]); err != nil {

     

       163
       +
       		return err

     

       164
       +
       	}

     

       165
       +
       	_, err := c.rwc.Write(c.buf.Bytes())

     

       166
       +
       	return err

     

       167
       +
       }

     

       168
       +
       

     

       169
       +
       func (c *conn) writeEndRequest(reqId uint16, appStatus int, protocolStatus uint8) error {

     

       170
       +
       	b := make([]byte, 8)

     

       171
       +
       	binary.BigEndian.PutUint32(b, uint32(appStatus))

     

       172
       +
       	b[4] = protocolStatus

     

       173
       +
       	return c.writeRecord(typeEndRequest, reqId, b)

     

       174
       +
       }

     

       175
       +
       

     

       176
       +
       func (c *conn) writePairs(recType recType, reqId uint16, pairs map[string]string) error {

     

       177
       +
       	w := newWriter(c, recType, reqId)

     

       178
       +
       	b := make([]byte, 8)

     

       179
       +
       	for k, v := range pairs {

     

       180
       +
       		n := encodeSize(b, uint32(len(k)))

     

       181
       +
       		n += encodeSize(b[n:], uint32(len(v)))

     

       182
       +
       		if _, err := w.Write(b[:n]); err != nil {

     

       183
       +
       			return err

     

       184
       +
       		}

     

       185
       +
       		if _, err := w.WriteString(k); err != nil {

     

       186
       +
       			return err

     

       187
       +
       		}

     

       188
       +
       		if _, err := w.WriteString(v); err != nil {

     

       189
       +
       			return err

     

       190
       +
       		}

     

       191
       +
       	}

     

       192
       +
       	w.Close()

     

       193
       +
       	return nil

     

       194
       +
       }

     

       195
       +
       

     

       196
       +
       func readSize(s []byte) (uint32, int) {

     

       197
       +
       	if len(s) == 0 {

     

       198
       +
       		return 0, 0

     

       199
       +
       	}

     

       200
       +
       	size, n := uint32(s[0]), 1

     

       201
       +
       	if size&(1<<7) != 0 {

     

       202
       +
       		if len(s) < 4 {

     

       203
       +
       			return 0, 0

     

       204
       +
       		}

     

       205
       +
       		n = 4

     

       206
       +
       		size = binary.BigEndian.Uint32(s)

     

       207
       +
       		size &^= 1 << 31

     

       208
       +
       	}

     

       209
       +
       	return size, n

     

       210
       +
       }

     

       211
       +
       

     

       212
       +
       func readString(s []byte, size uint32) string {

     

       213
       +
       	if size > uint32(len(s)) {

     

       214
       +
       		return ""

     

       215
       +
       	}

     

       216
       +
       	return string(s[:size])

     

       217
       +
       }

     

       218
       +
       

     

       219
       +
       func encodeSize(b []byte, size uint32) int {

     

       220
       +
       	if size > 127 {

     

       221
       +
       		size |= 1 << 31

     

       222
       +
       		binary.BigEndian.PutUint32(b, size)

     

       223
       +
       		return 4

     

       224
       +
       	}

     

       225
       +
       	b[0] = byte(size)

     

       226
       +
       	return 1

     

       227
       +
       }

     

       228
       +
       

     

       229
       +
       // bufWriter encapsulates bufio.Writer but also closes the underlying stream when

     

       230
       +
       // Closed.

     

       231
       +
       type bufWriter struct {

     

       232
       +
       	closer io.Closer

     

       233
       +
       	*bufio.Writer

     

       234
       +
       }

     

       235
       +
       

     

       236
       +
       func (w *bufWriter) Close() error {

     

       237
       +
       	if err := w.Writer.Flush(); err != nil {

     

       238
       +
       		w.closer.Close()

     

       239
       +
       		return err

     

       240
       +
       	}

     

       241
       +
       	return w.closer.Close()

     

       242
       +
       }

     

       243
       +
       

     

       244
       +
       func newWriter(c *conn, recType recType, reqId uint16) *bufWriter {

     

       245
       +
       	s := &streamWriter{c: c, recType: recType, reqId: reqId}

     

       246
       +
       	w := bufio.NewWriterSize(s, maxWrite)

     

       247
       +
       	return &bufWriter{s, w}

     

       248
       +
       }

     

       249
       +
       

     

       250
       +
       // streamWriter abstracts out the separation of a stream into discrete records.

     

       251
       +
       // It only writes maxWrite bytes at a time.

     

       252
       +
       type streamWriter struct {

     

       253
       +
       	c       *conn

     

       254
       +
       	recType recType

     

       255
       +
       	reqId   uint16

     

       256
       +
       }

     

       257
       +
       

     

       258
       +
       func (w *streamWriter) Write(p []byte) (int, error) {

     

       259
       +
       	nn := 0

     

       260
       +
       	for len(p) > 0 {

     

       261
       +
       		n := len(p)

     

       262
       +
       		if n > maxWrite {

     

       263
       +
       			n = maxWrite

     

       264
       +
       		}

     

       265
       +
       		if err := w.c.writeRecord(w.recType, w.reqId, p[:n]); err != nil {

     

       266
       +
       			return nn, err

     

       267
       +
       		}

     

       268
       +
       		nn += n

     

       269
       +
       		p = p[n:]

     

       270
       +
       	}

     

       271
       +
       	return nn, nil

     

       272
       +
       }

     

       273
       +
       

     

       274
       +
       func (w *streamWriter) Close() error {

     

       275
       +
       	// send empty record to close the stream

     

       276
       +
       	return w.c.writeRecord(w.recType, w.reqId, nil)

     

       277
       +
       }