diff options
Diffstat (limited to '2024/09/15')
| -rw-r--r-- | 2024/09/15/Advanced-C-binding-using-ocaml-ctypes-and-dune/index.html | 56 | ||||
| -rw-r--r-- | 2024/09/15/肩周炎和肩袖损伤的区别/index.html | 15 |
2 files changed, 35 insertions, 36 deletions
diff --git a/2024/09/15/Advanced-C-binding-using-ocaml-ctypes-and-dune/index.html b/2024/09/15/Advanced-C-binding-using-ocaml-ctypes-and-dune/index.html index 9f8963b8..a825fda7 100644 --- a/2024/09/15/Advanced-C-binding-using-ocaml-ctypes-and-dune/index.html +++ b/2024/09/15/Advanced-C-binding-using-ocaml-ctypes-and-dune/index.html @@ -200,21 +200,26 @@ <div class="post-content"> <p>I was working on a OCaml binding for <a target="_blank" rel="noopener" href="https://github.com/Haivision/srt">libsrt</a> last summer, to add support for SRT real-time input and output to <a target="_blank" rel="noopener" href="https://github.com/savonet/liquidsoap">liquidsoap</a>, and came across the need to access the <code>[sys/socket.h](https://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html)</code> C API.</p> <p>I had already decided to use the very elegant <code>[ocaml-ctypes](https://github.com/ocamllabs/ocaml-ctypes)</code> module for the SRT binding so I went with it and created a <code>[ocaml-sys-socket](https://github.com/toots/ocaml-sys-socket)</code> module using it as well. It was a very interesting experience that I would like to describe here!</p> -<h1 id="ocaml-ctypes"><a href="#ocaml-ctypes" class="headerlink" title="ocaml-ctypes"></a>ocaml-ctypes</h1><p>The idea behind OCaml ctypes is to create a binding against a C library without having to write C code, or as least as possible. The most straight-forward way of using it is via <code>[libffi](https://github.com/libffi/libffi)</code> , providing access to dynamically-loaded libraries.</p> +<h1>ocaml-ctypes</h1> +<p>The idea behind OCaml ctypes is to create a binding against a C library without having to write C code, or as least as possible. The most straight-forward way of using it is via <code>[libffi](https://github.com/libffi/libffi)</code> , providing access to dynamically-loaded libraries.</p> <p>The second way of using it is by letting the module generate the basic C stubs required to build and link against a shared library. This is the mode that we’re going to use here. In this mode, the programmer has to describe the C headers of the library they intent to bind to using dedicated OCaml modules, operators and types. From that description, ocaml-ctypes is able to generate the required glue for the binding.</p> <p>One advantage of using ocaml-ctypes is that the created bindings make as few assumptions as possible about the <a target="_blank" rel="noopener" href="https://caml.inria.fr/pub/docs/manual-ocaml/intfc.html">OCaml C interfacing API</a>. This is pretty nice, in particular since the <a target="_blank" rel="noopener" href="https://github.com/ocaml/ocaml">OCaml compiler</a> is moving pretty quickly these days (which is awesome!) and also if, perhaps one day, <a target="_blank" rel="noopener" href="https://github.com/ocaml-multicore/ocaml-multicore">support for multi-core</a> is added to the compiler, which will undoubtedly change the C interface API quite a bit.</p> -<h1 id="dune"><a href="#dune" class="headerlink" title="dune"></a>dune</h1><p><code>[dune](https://github.com/ocaml/dune)</code> (formally <code>jbuilder</code> ) is a build system for OCaml projects that has recently raised to much popularity, particularly due to its tight integration with the rest of the OCaml ecosystem, such as <code>[ocamlfind](http://projects.camlcity.org/projects/findlib.html)</code> and <code>[opam](https://opam.ocaml.org/)</code> .</p> +<h1>dune</h1> +<p><code>[dune](https://github.com/ocaml/dune)</code> (formally <code>jbuilder</code> ) is a build system for OCaml projects that has recently raised to much popularity, particularly due to its tight integration with the rest of the OCaml ecosystem, such as <code>[ocamlfind](http://projects.camlcity.org/projects/findlib.html)</code> and <code>[opam](https://opam.ocaml.org/)</code> .</p> <p>My personal motto in programming in general is that <em>“Simple things should be simple, but complex things should be possible”</em>. <code>dune</code> certainly does not fit into that category but, rather, makes some complex things extremely easy to setup. It’s the kind of tool that will make your life incredibly easier when what you intent to do fits well within their workflow but might not be easy to bend to some very specific niche use. We will see one such case below.</p> <p>At any rate, it’s been an amazing experience getting to learn how to use <code>dune</code> and the resulting code and build system is remarkably short and elegant, yet very powerful.</p> -<h1 id="socket-h"><a href="#socket-h" class="headerlink" title="socket.h"></a>socket.h</h1><p><code>socket.h</code> is the Unix header that describes the C API to various socket operations, IP version 4 and 6 as well as unix file sockets. There is also a windows API mimicking it, which makes most code using it easily portable to windows.</p> +<h1>socket.h</h1> +<p><code>socket.h</code> is the Unix header that describes the C API to various socket operations, IP version 4 and 6 as well as unix file sockets. There is also a windows API mimicking it, which makes most code using it easily portable to windows.</p> <p>Most network-based C libraries refer to <code>socket.h</code> to describe the type of socket that can be used with their API so it’s an important entry point for a lot of network operations and one that would be nice to support as generically as possible in OCaml.</p> <p>The catch, though, is that, most likely for historical reasons¹, the <a target="_blank" rel="noopener" href="https://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html">POSIX specifications</a> only <em>partially</em> defines some of the required data structures and types, which makes it possible to write C code using them but does not give enough information to write C bindings without having to use the compiler to parse the actual system-specific headers of the running host.</p> <p>For instance, here’s how the <code>sockaddr</code> structure is specified:</p> -<p>The <em><sys/socket.h></em> header defines the sockaddr structure that includes at least the following members:sa_family_t sa_family address family<br>char sa_data[] socket address (variable-length data)</p> +<p>The <em><sys/socket.h></em> header defines the sockaddr structure that includes at least the following members:sa_family_t sa_family address family<br> +char sa_data[] socket address (variable-length data)</p> <p>Likewise, here’s what is specified about the size of the <code>socklen_t</code> data type:</p> -<p><em><sys/socket.h></em> makes available a type, socklen_t, which is an unsigned opaque integral type of length of at least 32 bits.</p> +<p><em><sys/socket.h></em> makes available a type, socklen_t, which is an unsigned opaque integral type of length of at least 32 bits.</p> <p>Thus, in order to know the exact offset of <code>sa_family</code> inside the <code>sockaddr</code> structure or the actual size of a <code>socklen_t</code> integer, one has to include the OS-specific header, parse its definitions for that specific OS and, only then, is it possible to compute that offset or data size. Let’s see how it’s done in our binding now!</p> -<h1 id="Putting-it-together"><a href="#Putting-it-together" class="headerlink" title="Putting it together"></a>Putting it together</h1><p>The C binding requires 4 separate passes:</p> +<h1>Putting it together</h1> +<p>The C binding requires 4 separate passes:</p> <ul> <li>The <code>[constants](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/constants)</code> pass, which computes and exports some specific constant and data sizes, computed from the C headers</li> <li>The <code>[types](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/types)</code> pass, which, given the system-specific constants and sizes exported in the previous phase, defines the actual C data structure bindings.</li> @@ -222,73 +227,62 @@ <li>Finally, the <a target="_blank" rel="noopener" href="https://github.com/toots/ocaml-sys-socket/blob/master/src/sys-socket/sys_socket.mli">last pass</a> does a cleanup of the <code>stubs</code> pass to export a relevant and OCaml- (and <code>ocaml-ctypes</code>) specific public API that is to be used by users of the module.</li> </ul> <p><code>dune</code> makes each of these steps fairly easy to integrate into the next one, defining compilation elements and binaries to build before moving to the next pass.</p> -<h2 id="Constants-pass"><a href="#Constants-pass" class="headerlink" title="Constants pass"></a>Constants pass</h2><p>During that pass, we compute and export all required C values defined in the headers. We also add our own constants, which give us the sizes that the POSIX specifications leave up to the OS. Here’s the OCaml code for it:</p> +<h2 id="Constants-pass"><a class="header-anchor" href="#Constants-pass">¶</a>Constants pass</h2> +<p>During that pass, we compute and export all required C values defined in the headers. We also add our own constants, which give us the sizes that the POSIX specifications leave up to the OS. Here’s the OCaml code for it:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">module</span> <span class="type">Def</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) = <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">let</span> af_inet = <span class="type">S</span>.constant <span class="string">"AF_INET"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> af_inet6 = <span class="type">S</span>.constant <span class="string">"AF_INET6"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> af_unix = <span class="type">S</span>.constant <span class="string">"AF_UNIX"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> af_unspec = <span class="type">S</span>.constant <span class="string">"AF_UNSPEC"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> sa_data_len = <span class="type">S</span>.constant <span class="string">"SA_DATA_LEN"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> sa_family_len = <span class="type">S</span>.constant <span class="string">"SA_FAMILY_LEN"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> sock_dgram = <span class="type">S</span>.constant <span class="string">"SOCK_DGRAM"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> sock_stream = <span class="type">S</span>.constant <span class="string">"SOCK_STREAM"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> sock_seqpacket = <span class="type">S</span>.constant <span class="string">"SOCK_STREAM"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> socklen_t_len = <span class="type">S</span>.constant <span class="string">"SOCKLEN_T_LEN"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> ni_maxserv = <span class="type">S</span>.constant <span class="string">"NI_MAXSERV"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> ni_maxhost = <span class="type">S</span>.constant <span class="string">"NI_MAXHOST"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> ni_numerichost = <span class="type">S</span>.constant <span class="string">"NI_NUMERICHOST"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"> <span class="keyword">let</span> ni_numericserv = <span class="type">S</span>.constant <span class="string">"NI_NUMERICSERV"</span> <span class="type">S</span>.<span class="built_in">int</span></span><br><span class="line"><span class="keyword">end</span></span><br></pre></td></tr></table></figure> - <p>Pretty straightforward! Some of these constants are defined by the POSIX headers and some are custom defined for our needs, for instance <code>SOCKLEN_T_LEN</code> . Here’s how they are extracted, using the <code>dune</code> build configuration for <code>[gen_constants_c](https://github.com/toots/ocaml-sys-socket/blob/master/src/sys-socket/generator/gen_constants_c.ml)</code>:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> c_headers = <span class="string">"</span></span><br><span class="line"><span class="string">#ifdef _WIN32</span></span><br><span class="line"><span class="string"> #include <winsock2.h></span></span><br><span class="line"><span class="string"> #include <ws2tcpip.h></span></span><br><span class="line"><span class="string">#else</span></span><br><span class="line"><span class="string"> #include <sys/socket.h></span></span><br><span class="line"><span class="string"> #include <sys/un.h></span></span><br><span class="line"><span class="string"> #include <netdb.h></span></span><br><span class="line"><span class="string">#endif</span></span><br><span class="line"><span class="string">#define SA_DATA_LEN (sizeof(((struct sockaddr*)0)->sa_data))</span></span><br><span class="line"><span class="string">#define SA_FAMILY_LEN (sizeof(((struct sockaddr*)0)->sa_family))</span></span><br><span class="line"><span class="string">#define SOCKLEN_T_LEN (sizeof(socklen_t))</span></span><br><span class="line"><span class="string">#ifndef NI_MAXHOST</span></span><br><span class="line"><span class="string"> #define NI_MAXHOST 1025</span></span><br><span class="line"><span class="string">#endif</span></span><br><span class="line"><span class="string">#ifndef NI_MAXSERV</span></span><br><span class="line"><span class="string"> #define NI_MAXSERV 32</span></span><br><span class="line"><span class="string">#endif</span></span><br><span class="line"><span class="string">"</span></span><br><span class="line"><span class="keyword">let</span> <span class="literal">()</span> =</span><br><span class="line"> <span class="keyword">let</span> fname = <span class="type">Sys</span>.argv.(<span class="number">1</span>) <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> oc = open_out_bin fname <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> format =</span><br><span class="line"> <span class="type">Format</span>.formatter_of_out_channel oc</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> <span class="type">Format</span>.fprintf format <span class="string">"%s@\n"</span> c_headers;</span><br><span class="line"> <span class="type">Cstubs</span>.<span class="type">Types</span>.write_c format (<span class="keyword">module</span> <span class="type">Sys_socket_constants</span>.<span class="type">Def</span>);</span><br><span class="line"> <span class="type">Format</span>.pp_print_flush format <span class="literal">()</span>;</span><br><span class="line"> close_out oc</span><br></pre></td></tr></table></figure> - <p>This OCaml code makes use of <code>ocaml-ctypes</code> to build a binary that exports the OCaml interface defined by <code>Sys_socket_constants.Def</code> . Once compiled, its output looks like this:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">include</span> <span class="type">Ctypes</span></span><br><span class="line"><span class="keyword">let</span> lift x = x</span><br><span class="line"><span class="keyword">open</span> <span class="type">Ctypes_static</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="keyword">rec</span> field : <span class="keyword">type</span> t a. t typ -> <span class="built_in">string</span> -> a typ -> (a, t) field =</span><br><span class="line"> <span class="keyword">fun</span> s fname ftype -> <span class="keyword">match</span> s, fname <span class="keyword">with</span></span><br><span class="line"> | <span class="type">View</span> { ty }, _ -></span><br><span class="line"> <span class="keyword">let</span> { ftype; foffset; fname } = field ty fname ftype <span class="keyword">in</span></span><br><span class="line"> { ftype; foffset; fname }</span><br><span class="line"> | _ -> failwith (<span class="string">"Unexpected field "</span>^ fname)</span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="keyword">rec</span> seal : <span class="keyword">type</span> a. a typ -> <span class="built_in">unit</span> = <span class="keyword">function</span></span><br><span class="line"> | <span class="type">Struct</span> { tag; spec = <span class="type">Complete</span> _ } -></span><br><span class="line"> raise (<span class="type">ModifyingSealedType</span> tag)</span><br><span class="line"> | <span class="type">Union</span> { utag; uspec = <span class="type">Some</span> _ } -></span><br><span class="line"> raise (<span class="type">ModifyingSealedType</span> utag)</span><br><span class="line"> | <span class="type">View</span> { ty } -> seal ty</span><br><span class="line"> | _ -></span><br><span class="line"> raise (<span class="type">Unsupported</span> <span class="string">"Sealing a non-structured type"</span>)</span><br><span class="line"></span><br><span class="line"><span class="keyword">type</span> <span class="symbol">'a</span> const = <span class="symbol">'a</span></span><br><span class="line"><span class="keyword">let</span> constant (<span class="keyword">type</span> t) name (t : t typ) : t = <span class="keyword">match</span> t, name <span class="keyword">with</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"NI_NUMERICSERV"</span> -></span><br><span class="line"> <span class="number">8</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"NI_NUMERICHOST"</span> -></span><br><span class="line"> <span class="number">2</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"NI_MAXHOST"</span> -></span><br><span class="line"> <span class="number">1025</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"NI_MAXSERV"</span> -></span><br><span class="line"> <span class="number">32</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"SOCKLEN_T_LEN"</span> -></span><br><span class="line"> <span class="number">4</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"SOCK_STREAM"</span> -></span><br><span class="line"> <span class="number">1</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"SOCK_STREAM"</span> -></span><br><span class="line"> <span class="number">1</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"SOCK_DGRAM"</span> -></span><br><span class="line"> <span class="number">2</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"SA_FAMILY_LEN"</span> -></span><br><span class="line"> <span class="number">1</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"SA_DATA_LEN"</span> -></span><br><span class="line"> <span class="number">14</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"AF_UNSPEC"</span> -></span><br><span class="line"> <span class="number">0</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"AF_UNIX"</span> -></span><br><span class="line"> <span class="number">1</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"AF_INET6"</span> -></span><br><span class="line"> <span class="number">30</span></span><br><span class="line"> | <span class="type">Ctypes_static</span>.<span class="type">Primitive</span> <span class="type">Cstubs_internals</span>.<span class="type">Int</span>, <span class="string">"AF_INET"</span> -></span><br><span class="line"> <span class="number">2</span></span><br><span class="line"> | _, s -> failwith (<span class="string">"unmatched constant: "</span>^ s)</span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> enum (<span class="keyword">type</span> a) name ?typedef ?unexpected (alist : (a * <span class="built_in">int64</span>) <span class="built_in">list</span>) =</span><br><span class="line"> <span class="keyword">match</span> name <span class="keyword">with</span></span><br><span class="line"> | s -></span><br><span class="line"> failwith (<span class="string">"unmatched enum: "</span>^ s)</span><br></pre></td></tr></table></figure> - <p>The files used to describe how to build this binary using <code>dune</code> are located in a separate <code>[generator](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/generator)</code> directory. Here’s the entry to build this one:</p> <figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line">(executable</span><br><span class="line"> (name gen_constants_c)</span><br><span class="line"> (modules gen_constants_c)</span><br><span class="line"> (libraries sys-socket.constants ctypes.stubs))</span><br><span class="line"></span><br><span class="line">(rule</span><br><span class="line"> (targets gen_constants.c)</span><br><span class="line"> (deps (:gen ./gen_constants_c.exe))</span><br><span class="line"> (action (run %{gen} %{targets})))</span><br><span class="line"></span><br><span class="line">(rule</span><br><span class="line"> (targets gen_constants_c)</span><br><span class="line"> (deps (:c_code ./gen_constants.c))</span><br><span class="line"> (action (run %{ocaml-config:c_compiler} -I %{lib:ctypes:} -I %{ocaml-config:standard_library} -o %{targets} %{c_code})))</span><br></pre></td></tr></table></figure> - <p>This executable is compiled during the next phase. Let’s move into it now!</p> -<h2 id="Types-pass"><a href="#Types-pass" class="headerlink" title="Types pass"></a>Types pass</h2><p>During that phase, we use the constants exported during the previous phase to describe the various C structures and types. This is by far the most complex part of the code, making use of first-class modules and several OCaml tricks.</p> +<h2 id="Types-pass"><a class="header-anchor" href="#Types-pass">¶</a>Types pass</h2> +<p>During that phase, we use the constants exported during the previous phase to describe the various C structures and types. This is by far the most complex part of the code, making use of first-class modules and several OCaml tricks.</p> <p>First, let’s look at how we tell <code>dune</code> that we need to generate the <code>.ml</code> file exporting our required constants from the previous pass:</p> <figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">(rule</span><br><span class="line"> (targets sys_socket_generated_constants.ml)</span><br><span class="line"> (deps (:exec ../generator/exec.sh)</span><br><span class="line"> (:gen ../generator/gen_constants_c))</span><br><span class="line"> (action (with-stdout-to %{targets}</span><br><span class="line"> (system "%{exec} %{ocaml-config:system} %{gen}"))))</span><br></pre></td></tr></table></figure> - <p>With only this information, if the code refers to a <code>Sys_socket_generated_constants</code> module, <code>dune</code> will know that this module needs to be generated and how to do it. We will explain later the use of the <code>exec.sh</code> wrapper here.</p> <p>Now that we can make use of the exported constants in our OCaml code, let’s see how we define the <code>Socklen</code> module, exporting abstract types and interface to use <code>socklen_t</code> integers:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">module</span> <span class="type">Constants</span> = <span class="type">Sys_socket_constants</span>.<span class="type">Def</span>(<span class="type">Sys_socket_generated_constants</span>)</span><br><span class="line"></span><br><span class="line"><span class="keyword">module</span> <span class="keyword">type</span> <span class="type">Socklen</span> = <span class="keyword">functor</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) -> <span class="keyword">sig</span></span><br><span class="line"> <span class="keyword">type</span> socklen</span><br><span class="line"> <span class="keyword">val</span> socklen_t : socklen <span class="type">S</span>.typ</span><br><span class="line"> <span class="keyword">val</span> int_of_socklen : socklen -> <span class="built_in">int</span></span><br><span class="line"> <span class="keyword">val</span> socklen_of_int : <span class="built_in">int</span> -> socklen</span><br><span class="line"><span class="keyword">end</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> socklen : (<span class="keyword">module</span> <span class="type">Socklen</span>) =</span><br><span class="line"> <span class="keyword">match</span> <span class="type">Constants</span>.socklen_t_len <span class="keyword">with</span></span><br><span class="line"> | <span class="number">4</span> -> (<span class="keyword">module</span> <span class="keyword">functor</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) -> <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">type</span> socklen = <span class="type">Unsigned</span>.uint32</span><br><span class="line"> <span class="keyword">let</span> socklen_t = <span class="type">S</span>.uint32_t</span><br><span class="line"> <span class="keyword">let</span> int_of_socklen = <span class="type">Unsigned</span>.<span class="type">UInt32</span>.to_int</span><br><span class="line"> <span class="keyword">let</span> socklen_of_int = <span class="type">Unsigned</span>.<span class="type">UInt32</span>.of_int</span><br><span class="line"> <span class="keyword">end</span>)</span><br><span class="line"> | <span class="number">8</span> -> (<span class="keyword">module</span> <span class="keyword">functor</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) -> <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">type</span> socklen = <span class="type">Unsigned</span>.uint64</span><br><span class="line"> <span class="keyword">let</span> socklen_t = <span class="type">S</span>.uint64_t</span><br><span class="line"> <span class="keyword">let</span> int_of_socklen = <span class="type">Unsigned</span>.<span class="type">UInt64</span>.to_int</span><br><span class="line"> <span class="keyword">let</span> socklen_of_int = <span class="type">Unsigned</span>.<span class="type">UInt64</span>.of_int</span><br><span class="line"> <span class="keyword">end</span>)</span><br><span class="line"> | _ -> <span class="keyword">assert</span> <span class="literal">false</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">module</span> <span class="type">Socklen</span> = (<span class="keyword">val</span> socklen : <span class="type">Socklen</span>)</span><br></pre></td></tr></table></figure> - <p>As you can see, we make use of first-order modules and the size of the <code>socklen_t</code> integer to define the right API for the compiling host. Now let’s see how we define the <code>sockaddr</code> interface:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">module</span> <span class="keyword">type</span> <span class="type">SaFamily</span> = <span class="keyword">sig</span></span><br><span class="line"> <span class="keyword">type</span> sa_family</span><br><span class="line"> <span class="keyword">val</span> int_of_sa_family : sa_family -> <span class="built_in">int</span></span><br><span class="line"> <span class="keyword">val</span> sa_family_of_int : <span class="built_in">int</span> -> sa_family</span><br><span class="line"> </span><br><span class="line"> <span class="keyword">module</span> <span class="type">T</span> : <span class="keyword">functor</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) -> <span class="keyword">sig</span></span><br><span class="line"> <span class="keyword">val</span> t : sa_family <span class="type">S</span>.typ</span><br><span class="line"> <span class="keyword">end</span></span><br><span class="line"><span class="keyword">end</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> saFamily : (<span class="keyword">module</span> <span class="type">SaFamily</span>) =</span><br><span class="line"> <span class="keyword">match</span> <span class="type">Constants</span>.sa_family_len <span class="keyword">with</span></span><br><span class="line"> | <span class="number">1</span> -> (<span class="keyword">module</span> <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">type</span> sa_family = <span class="type">Unsigned</span>.uint8</span><br><span class="line"> <span class="keyword">let</span> int_of_sa_family = <span class="type">Unsigned</span>.<span class="type">UInt8</span>.to_int</span><br><span class="line"> <span class="keyword">let</span> sa_family_of_int = <span class="type">Unsigned</span>.<span class="type">UInt8</span>.of_int </span><br><span class="line"> <span class="keyword">module</span> <span class="type">T</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) = <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">let</span> t = <span class="type">S</span>.uint8_t</span><br><span class="line"> <span class="keyword">end</span></span><br><span class="line"> <span class="keyword">end</span>)</span><br><span class="line">...</span><br><span class="line"></span><br><span class="line"><span class="keyword">module</span> <span class="type">SaFamily</span> = (<span class="keyword">val</span> saFamily : <span class="type">SaFamily</span>)</span><br><span class="line"></span><br><span class="line"><span class="keyword">module</span> <span class="type">Def</span> (<span class="type">S</span> : <span class="type">Cstubs</span>.<span class="type">Types</span>.<span class="type">TYPE</span>) = <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">include</span> <span class="type">Constants</span></span><br><span class="line"></span><br><span class="line"> <span class="keyword">include</span> <span class="type">Socklen</span>(<span class="type">S</span>)</span><br><span class="line"></span><br><span class="line"> <span class="keyword">include</span> <span class="type">SaFamily</span></span><br><span class="line"></span><br><span class="line"> <span class="keyword">module</span> <span class="type">SaFamilyT</span> = <span class="type">SaFamily</span>.<span class="type">T</span>(<span class="type">S</span>)</span><br><span class="line"></span><br><span class="line"> <span class="keyword">let</span> sa_family_t = <span class="type">S</span>.typedef <span class="type">SaFamilyT</span>.t <span class="string">"sa_family_t"</span></span><br><span class="line"></span><br><span class="line"> <span class="keyword">module</span> <span class="type">Sockaddr</span> = <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">type</span> t = <span class="built_in">unit</span></span><br><span class="line"> <span class="keyword">let</span> t = <span class="type">S</span>.structure <span class="string">"sockaddr"</span></span><br><span class="line"> <span class="keyword">let</span> sa_family = <span class="type">S</span>.field t <span class="string">"sa_family"</span> sa_family_t</span><br><span class="line"> <span class="keyword">let</span> sa_data = <span class="type">S</span>.field t <span class="string">"sa_data"</span> (<span class="type">S</span>.<span class="built_in">array</span> sa_data_len <span class="type">S</span>.<span class="built_in">char</span>)</span><br><span class="line"> <span class="keyword">let</span> <span class="literal">()</span> = <span class="type">S</span>.seal t</span><br><span class="line"> <span class="keyword">end</span></span><br><span class="line"> </span><br><span class="line"> ...</span><br><span class="line"><span class="keyword">end</span></span><br></pre></td></tr></table></figure> - <p>Here, too, we make use of the size of <code>sa_family</code> as exported previously to define the right structure fields.</p> <p>Next step, we need to compile this interface again to export the right offset for the various structures that have been defined. That’s <code>dune</code>’s job again!</p> <p>First, the generator code:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> c_headers = <span class="string">"</span></span><br><span class="line"><span class="string">#ifdef _WIN32</span></span><br><span class="line"><span class="string"> #include <winsock2.h></span></span><br><span class="line"><span class="string"> #include <ws2tcpip.h></span></span><br><span class="line"><span class="string">#else</span></span><br><span class="line"><span class="string"> #include <sys/socket.h></span></span><br><span class="line"><span class="string"> #include <sys/un.h></span></span><br><span class="line"><span class="string"> #include <netinet/in.h></span></span><br><span class="line"><span class="string"> #include <netdb.h></span></span><br><span class="line"><span class="string">#endif</span></span><br><span class="line"><span class="string">"</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="literal">()</span> =</span><br><span class="line"> <span class="keyword">let</span> fname = <span class="type">Sys</span>.argv.(<span class="number">1</span>) <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> oc = open_out_bin fname <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> format =</span><br><span class="line"> <span class="type">Format</span>.formatter_of_out_channel oc</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> <span class="type">Format</span>.fprintf format <span class="string">"%s@\n"</span> c_headers;</span><br><span class="line"> <span class="type">Cstubs</span>.<span class="type">Types</span>.write_c format (<span class="keyword">module</span> <span class="type">Sys_socket_types</span>.<span class="type">Def</span>);</span><br><span class="line"> <span class="type">Format</span>.pp_print_flush format <span class="literal">()</span>;</span><br><span class="line"> close_out oc</span><br></pre></td></tr></table></figure> - <p>And the build instructions:</p> <figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line">(executable</span><br><span class="line"> (name gen_types_c)</span><br><span class="line"> (modules gen_types_c)</span><br><span class="line"> (libraries sys-socket.types ctypes.stubs))</span><br><span class="line"></span><br><span class="line">(rule</span><br><span class="line"> (targets gen_types.c)</span><br><span class="line"> (deps (:gen ./gen_types_c.exe))</span><br><span class="line"> (action (run %{gen} %{targets})))</span><br><span class="line"></span><br><span class="line">(rule</span><br><span class="line"> (targets gen_types_c)</span><br><span class="line"> (deps (:c_code ./gen_types.c))</span><br><span class="line"> (action (run %{ocaml-config:c_compiler} -I %{lib:ctypes:} -I %{ocaml-config:standard_library} -o %{targets} %{c_code})))</span><br></pre></td></tr></table></figure> - <p>Once, compiled, the exported <code>.ml</code> looks like this:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">include</span> <span class="type">Ctypes</span></span><br><span class="line"><span class="keyword">let</span> lift x = x</span><br><span class="line"><span class="keyword">open</span> <span class="type">Ctypes_static</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="keyword">rec</span> field : <span class="keyword">type</span> t a. t typ -> <span class="built_in">string</span> -> a typ -> (a, t) field =</span><br><span class="line"> <span class="keyword">fun</span> s fname ftype -> <span class="keyword">match</span> s, fname <span class="keyword">with</span></span><br><span class="line">...</span><br><span class="line"> | <span class="type">Struct</span> ({ tag = <span class="string">"sockaddr"</span>} <span class="keyword">as</span> s'), <span class="string">"sa_data"</span> -></span><br><span class="line"> <span class="keyword">let</span> f = {ftype; fname; foffset = <span class="number">2</span>} <span class="keyword">in</span></span><br><span class="line"> (s'.fields <- <span class="type">BoxedField</span> f :: s'.fields; f)</span><br><span class="line"> | <span class="type">Struct</span> ({ tag = <span class="string">"sockaddr"</span>} <span class="keyword">as</span> s'), <span class="string">"sa_family"</span> -></span><br><span class="line"> <span class="keyword">let</span> f = {ftype; fname; foffset = <span class="number">1</span>} <span class="keyword">in</span></span><br><span class="line"> (s'.fields <- <span class="type">BoxedField</span> f :: s'.fields; f)</span><br><span class="line"> | <span class="type">View</span> { ty }, _ -></span><br><span class="line"> <span class="keyword">let</span> { ftype; foffset; fname } = field ty fname ftype <span class="keyword">in</span></span><br><span class="line"> { ftype; foffset; fname }</span><br><span class="line"> | _ -> failwith (<span class="string">"Unexpected field "</span>^ fname)</span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="keyword">rec</span> seal : <span class="keyword">type</span> a. a typ -> <span class="built_in">unit</span> = <span class="keyword">function</span></span><br><span class="line">...</span><br><span class="line"> | <span class="type">Struct</span> ({ tag = <span class="string">"sockaddr_storage"</span>; spec = <span class="type">Incomplete</span> _ } <span class="keyword">as</span> s') -></span><br><span class="line"> s'.spec <- <span class="type">Complete</span> { size = <span class="number">128</span>; align = <span class="number">8</span> }</span><br><span class="line"> | <span class="type">Struct</span> ({ tag = <span class="string">"sockaddr"</span>; spec = <span class="type">Incomplete</span> _ } <span class="keyword">as</span> s') -></span><br><span class="line"> s'.spec <- <span class="type">Complete</span> { size = <span class="number">16</span>; align = <span class="number">1</span> }</span><br><span class="line"> | <span class="type">Struct</span> { tag; spec = <span class="type">Complete</span> _ } -></span><br><span class="line"> raise (<span class="type">ModifyingSealedType</span> tag)</span><br><span class="line"> | <span class="type">Union</span> { utag; uspec = <span class="type">Some</span> _ } -></span><br><span class="line"> raise (<span class="type">ModifyingSealedType</span> utag)</span><br><span class="line"> | <span class="type">View</span> { ty } -> seal ty</span><br><span class="line"> | _ -></span><br><span class="line"> raise (<span class="type">Unsupported</span> <span class="string">"Sealing a non-structured type"</span>)</span><br><span class="line"></span><br><span class="line"><span class="keyword">type</span> <span class="symbol">'a</span> const = <span class="symbol">'a</span></span><br><span class="line"><span class="keyword">let</span> constant (<span class="keyword">type</span> t) name (t : t typ) : t = <span class="keyword">match</span> t, name <span class="keyword">with</span></span><br><span class="line"> | _, s -> failwith (<span class="string">"unmatched constant: "</span>^ s)</span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> enum (<span class="keyword">type</span> a) name ?typedef ?unexpected (alist : (a * <span class="built_in">int64</span>) <span class="built_in">list</span>) =</span><br><span class="line"> <span class="keyword">match</span> name <span class="keyword">with</span></span><br><span class="line"> | s -></span><br><span class="line"> failwith (<span class="string">"unmatched enum: "</span>^ s)</span><br></pre></td></tr></table></figure> - <p>As you can see, this exports all the offsets required to access the fields inside a <code>sockaddr_t</code> structure. We’re now ready to move to the final stage, which is the actual binding stubs!</p> -<h2 id="Binding-stubs"><a href="#Binding-stubs" class="headerlink" title="Binding stubs"></a>Binding stubs</h2><p>First step in this pass, just like with the previous ones, we need to configure <code>dune</code> to be able to build the exported <code>.ml</code> code from the <code>types</code> pass:</p> +<h2 id="Binding-stubs"><a class="header-anchor" href="#Binding-stubs">¶</a>Binding stubs</h2> +<p>First step in this pass, just like with the previous ones, we need to configure <code>dune</code> to be able to build the exported <code>.ml</code> code from the <code>types</code> pass:</p> <figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">(rule</span><br><span class="line"> (targets sys_socket_generated_types.ml)</span><br><span class="line"> (deps (:exec ../generator/exec.sh)</span><br><span class="line"> (:gen ../generator/gen_types_c))</span><br><span class="line"> (action (with-stdout-to %{targets}</span><br><span class="line"> (system "%{exec} %{ocaml-config:system} %{gen}"))))</span><br></pre></td></tr></table></figure> - <p>And we can now define the proper bindings. Here’s how it looks like:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">open</span> <span class="type">Ctypes</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">module</span> <span class="type">Def</span> (<span class="type">F</span> : <span class="type">Cstubs</span>.<span class="type">FOREIGN</span>) = <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">open</span> <span class="type">F</span></span><br><span class="line"></span><br><span class="line"> <span class="keyword">module</span> <span class="type">Types</span> = <span class="type">Sys_socket_types</span>.<span class="type">Def</span>(<span class="type">Sys_socket_generated_types</span>)</span><br><span class="line"></span><br><span class="line"> <span class="keyword">open</span> <span class="type">Types</span></span><br><span class="line"></span><br><span class="line"> <span class="keyword">let</span> getnameinfo = foreign <span class="string">"getnameinfo"</span> (ptr sockaddr_t @-> socklen_t @-> ptr <span class="built_in">char</span> @-> socklen_t @-> ptr <span class="built_in">char</span> @-> socklen_t @-> <span class="built_in">int</span> @-> (returning <span class="built_in">int</span>))</span><br><span class="line"></span><br><span class="line">...</span><br><span class="line"><span class="keyword">end</span></span><br></pre></td></tr></table></figure> - -<p>As you can see, we’re exporting the <code>getnameinfo</code> function, taking various arguments, including a pointer to a <code>sockaddr_t</code> structure and a couple of <code>socklen_t</code> integers, making use of all the various data types and structures previously defined. The exact specifications of this function can be found <a target="_blank" rel="noopener" href="https://pubs.opengroup.org/onlinepubs/009695399/functions/getnameinfo.html">here</a>. We can now define out top-level API..</p> -<h2 id="Final-API"><a href="#Final-API" class="headerlink" title="Final API"></a>Final API</h2><p>Building upon the previous modules, we export various OCaml idiomatic APIs that the binding user can now use to build new bindings against the <code>socket.h</code> APIs.</p> +<p>As you can see, we’re exporting the <code>getnameinfo</code> function, taking various arguments, including a pointer to a <code>sockaddr_t</code> structure and a couple of <code>socklen_t</code> integers, making use of all the various data types and structures previously defined. The exact specifications of this function can be found <a target="_blank" rel="noopener" href="https://pubs.opengroup.org/onlinepubs/009695399/functions/getnameinfo.html">here</a>. We can now define out top-level API…</p> +<h2 id="Final-API"><a class="header-anchor" href="#Final-API">¶</a>Final API</h2> +<p>Building upon the previous modules, we export various OCaml idiomatic APIs that the binding user can now use to build new bindings against the <code>socket.h</code> APIs.</p> <p>Just like with the previous steps, first we need to configure the build system:</p> <figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">(rule</span><br><span class="line"> (targets sys_socket_generated_stubs.ml)</span><br><span class="line"> (deps (:gen ./generator/gen_stubs.exe))</span><br><span class="line"> (action (run %{gen} ml %{targets})))</span><br><span class="line"></span><br><span class="line">(rule</span><br><span class="line"> (targets sys_socket_generated_stubs.c)</span><br><span class="line"> (deps (:gen ./generator/gen_stubs.exe))</span><br><span class="line"> (action (run %{gen} c %{targets})))</span><br></pre></td></tr></table></figure> - <p>This time, we need <code>ocaml-ctypes</code> to generate two compilation units: a <code>.ml</code> file describing the API exported during the <code>stubs</code> phase, as well as the C code to glue it with the C APIs. Here’s the code for that generator:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">let</span> c_headers = <span class="string">"</span></span><br><span class="line"><span class="string">#ifdef _WIN32</span></span><br><span class="line"><span class="string"> #include <winsock2.h></span></span><br><span class="line"><span class="string"> #include <ws2tcpip.h></span></span><br><span class="line"><span class="string">#else</span></span><br><span class="line"><span class="string"> #include <sys/socket.h></span></span><br><span class="line"><span class="string"> #include <netinet/in.h></span></span><br><span class="line"><span class="string"> #include <arpa/inet.h></span></span><br><span class="line"><span class="string"> #include <netdb.h></span></span><br><span class="line"><span class="string">#endif</span></span><br><span class="line"><span class="string">#include <string.h></span></span><br><span class="line"><span class="string">"</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> <span class="literal">()</span> =</span><br><span class="line"> <span class="keyword">let</span> mode = <span class="type">Sys</span>.argv.(<span class="number">1</span>) <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> fname = <span class="type">Sys</span>.argv.(<span class="number">2</span>) <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> oc = open_out_bin fname <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> format =</span><br><span class="line"> <span class="type">Format</span>.formatter_of_out_channel oc</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> fn =</span><br><span class="line"> <span class="keyword">match</span> mode <span class="keyword">with</span></span><br><span class="line"> | <span class="string">"ml"</span> -> <span class="type">Cstubs</span>.write_ml</span><br><span class="line"> | <span class="string">"c"</span> -></span><br><span class="line"> <span class="type">Format</span>.fprintf format <span class="string">"%s@\n"</span> c_headers;</span><br><span class="line"> <span class="type">Cstubs</span>.write_c</span><br><span class="line"> | _ -> <span class="keyword">assert</span> <span class="literal">false</span></span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> fn ~concurrency:<span class="type">Cstubs</span>.unlocked format ~prefix:<span class="string">"sys_socket"</span> (<span class="keyword">module</span> <span class="type">Sys_socket_stubs</span>.<span class="type">Def</span>);</span><br><span class="line"> <span class="type">Format</span>.pp_print_flush format <span class="literal">()</span>;</span><br><span class="line"> close_out oc</span><br></pre></td></tr></table></figure> - <p>The exported <code>.ml</code> and <code>.c</code> files are omitted here for simplicity but the reader can generated them themselves from the <code>[ocaml-sys-socket](https://github.com/toots/ocaml-sys-socket)</code> repository if they are curious about their actual content.</p> <p>We can now export our top-level API:</p> <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">open</span> <span class="type">Ctypes</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">include</span> <span class="type">Sys_socket_types</span>.<span class="type">SaFamily</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">include</span> <span class="type">Sys_socket_stubs</span>.<span class="type">Def</span>(<span class="type">Sys_socket_generated_stubs</span>)</span><br><span class="line"></span><br><span class="line"><span class="keyword">type</span> socklen = <span class="type">Types</span>.socklen</span><br><span class="line"><span class="keyword">let</span> socklen_t = <span class="type">Types</span>.socklen_t</span><br><span class="line"><span class="keyword">let</span> int_of_socklen = <span class="type">Types</span>.int_of_socklen</span><br><span class="line"><span class="keyword">let</span> socklen_of_int = <span class="type">Types</span>.socklen_of_int</span><br><span class="line"></span><br><span class="line"><span class="keyword">module</span> <span class="type">Sockaddr</span> = <span class="keyword">struct</span></span><br><span class="line"> <span class="keyword">include</span> <span class="type">Types</span>.<span class="type">Sockaddr</span></span><br><span class="line"> <span class="keyword">let</span> from_sockaddr_storage = from_sockaddr_storage t</span><br><span class="line"> <span class="keyword">let</span> sa_data_len = <span class="type">Types</span>.sa_data_len</span><br><span class="line"><span class="keyword">end</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">let</span> getnameinfo sockaddr_ptr =</span><br><span class="line"> <span class="keyword">let</span> maxhost = <span class="type">Types</span>.ni_maxhost <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> s = allocate_n <span class="built_in">char</span> ~count:maxhost <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> maxserv = <span class="type">Types</span>.ni_maxserv <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> p = allocate_n <span class="built_in">char</span> ~count:maxserv <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">match</span> getnameinfo sockaddr_ptr (socklen_of_int (sizeof sockaddr_t))</span><br><span class="line"> s (socklen_of_int maxhost) </span><br><span class="line"> p (socklen_of_int maxserv)</span><br><span class="line"> (<span class="type">Types</span>.ni_numerichost <span class="keyword">lor</span></span><br><span class="line"> <span class="type">Types</span>.ni_numericserv) <span class="keyword">with</span></span><br><span class="line"> | <span class="number">0</span> -></span><br><span class="line"> <span class="keyword">let</span> host =</span><br><span class="line"> <span class="keyword">let</span> length =</span><br><span class="line"> <span class="type">Unsigned</span>.<span class="type">Size_t</span>.to_int</span><br><span class="line"> (strnlen s (<span class="type">Unsigned</span>.<span class="type">Size_t</span>.of_int maxhost))</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> string_from_ptr s ~length</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> port =</span><br><span class="line"> <span class="keyword">let</span> length =</span><br><span class="line"> <span class="type">Unsigned</span>.<span class="type">Size_t</span>.to_int</span><br><span class="line"> (strnlen p (<span class="type">Unsigned</span>.<span class="type">Size_t</span>.of_int maxserv))</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">let</span> port =</span><br><span class="line"> string_from_ptr p ~length</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> <span class="keyword">try</span></span><br><span class="line"> int_of_string port</span><br><span class="line"> <span class="keyword">with</span> _ -></span><br><span class="line"> <span class="keyword">match</span> getservbyname p null <span class="keyword">with</span></span><br><span class="line"> | ptr <span class="keyword">when</span> is_null ptr -> failwith <span class="string">"getnameinfo"</span></span><br><span class="line"> | ptr -></span><br><span class="line"> <span class="type">Unsigned</span>.<span class="type">UInt16</span>.to_int</span><br><span class="line"> (ntohs (!@ (ptr |-> <span class="type">Types</span>.<span class="type">Servent</span>.s_port)))</span><br><span class="line"> <span class="keyword">in</span></span><br><span class="line"> host, port</span><br><span class="line"> | _ -> failwith <span class="string">"getnameinfo"</span></span><br><span class="line"></span><br><span class="line">...</span><br></pre></td></tr></table></figure> - <figure class="highlight ocaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">open</span> <span class="type">Ctypes</span></span><br><span class="line"></span><br><span class="line"><span class="comment">(** Ctypes routines for C type socklen_t. *)</span></span><br><span class="line"><span class="keyword">type</span> socklen</span><br><span class="line"><span class="keyword">val</span> socklen_t : socklen typ</span><br><span class="line"><span class="keyword">val</span> int_of_socklen : socklen -> <span class="built_in">int</span></span><br><span class="line"><span class="keyword">val</span> socklen_of_int : <span class="built_in">int</span> -> socklen</span><br><span class="line"></span><br><span class="line"><span class="comment">(** Generic sockaddr_t structure. *)</span></span><br><span class="line"><span class="keyword">module</span> <span class="type">Sockaddr</span> : <span class="keyword">sig</span></span><br><span class="line"> <span class="keyword">type</span> t</span><br><span class="line"> <span class="keyword">val</span> t : t structure typ</span><br><span class="line"> <span class="keyword">val</span> sa_family : (sa_family, t structure) field</span><br><span class="line"> <span class="keyword">val</span> sa_data : (<span class="built_in">char</span> carray, t structure) field</span><br><span class="line"> <span class="keyword">val</span> sa_data_len : <span class="built_in">int</span></span><br><span class="line"></span><br><span class="line"> <span class="keyword">val</span> from_sockaddr_storage : <span class="type">SockaddrStorage</span>.t structure ptr -> t structure ptr</span><br><span class="line"><span class="keyword">end</span></span><br><span class="line"></span><br><span class="line"><span class="comment">(** IP address conversion functions. *)</span></span><br><span class="line"><span class="keyword">val</span> getnameinfo : sockaddr ptr -> <span class="built_in">string</span> * <span class="built_in">int</span></span><br><span class="line"></span><br><span class="line">...</span><br></pre></td></tr></table></figure> - <p>That’s it! We now have <code>ocaml-ctypes</code> specific data types and structures that can be used to interface with the host’s native <code>socket.h</code> APIs. Note that we also worked on top of the original low-level binding to <code>getnameinfo</code> to export a higher-level function more idiomatic to the OCaml language.</p> -<h1 id="Lagniappe-cross-compilation-to-Windows"><a href="#Lagniappe-cross-compilation-to-Windows" class="headerlink" title="Lagniappe: cross-compilation to Windows"></a>Lagniappe: cross-compilation to Windows</h1><p>On windows platforms, <code>liquidsoap</code> is compiled using <code>[ocaml-cross-windows](https://github.com/ocaml-cross/opam-cross-windows)</code> and, since windows does have compatible socket APIs, we wanted to also look at cross-compiling for the windows target, which is where we hit a snag on the current <code>dune</code> support.</p> +<h1>Lagniappe: cross-compilation to Windows</h1> +<p>On windows platforms, <code>liquidsoap</code> is compiled using <code>[ocaml-cross-windows](https://github.com/ocaml-cross/opam-cross-windows)</code> and, since windows does have compatible socket APIs, we wanted to also look at cross-compiling for the windows target, which is where we hit a snag on the current <code>dune</code> support.</p> <p>The problem is that, at each intermediary steps, in the case of a cross-compilation, the compiled binaries need to use the target’s OS headers and not the host’s headers, otherwise we end up using offsets specific to e.g. Debian but for a windows binary.</p> <p>In this case, this means that the compiled <code>.exe</code> binaries need to be windows binaries and that we need to execute them as windows native binaries, using <code>[wine](https://www.winehq.org/)</code> .</p> <p><code>dune</code> has a truly amazing <a target="_blank" rel="noopener" href="https://dune.readthedocs.io/en/latest/cross-compilation.html">support for cross-compiling</a>, which we do not cover here, but, unfortunately, its primitives for building and executing binaries do not yet cover this use case. Thus we had to trick it into compiling things the way we wanted to do, which why we are using the <code>exec.sh</code> wrapper. Here’s its code:</p> <figure class="highlight sh"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#!/bin/sh</span></span><br><span class="line"></span><br><span class="line">SYSTEM=<span class="variable">$1</span></span><br><span class="line">CMD=<span class="variable">$2</span></span><br><span class="line">ARG=<span class="variable">$3</span></span><br><span class="line"></span><br><span class="line"><span class="keyword">if</span> <span class="built_in">test</span> <span class="string">"<span class="variable">${SYSTEM}</span>"</span> = <span class="string">"mingw"</span>; <span class="keyword">then</span></span><br><span class="line"> wine <span class="variable">$CMD</span> <span class="variable">$ARG</span></span><br><span class="line"><span class="keyword">elif</span> <span class="built_in">test</span> <span class="string">"<span class="variable">${SYSTEM}</span>"</span> = <span class="string">"mingw64"</span>; <span class="keyword">then</span></span><br><span class="line"> wine64 <span class="variable">$CMD</span> <span class="variable">$ARG</span></span><br><span class="line"><span class="keyword">else</span></span><br><span class="line"> <span class="variable">$CMD</span> <span class="variable">$ARG</span></span><br></pre></td></tr></table></figure> - <p>Now, you can go back to the previous <code>dune</code> files and see how this wrapper allows to execute binaries according to the system that the corresponding <code>ocamlopt</code> compiler has been configured to build for.</p> -<h1 id="Conclusion"><a href="#Conclusion" class="headerlink" title="Conclusion"></a>Conclusion</h1><p>It’s been a fun time working on this binding! It’s amazing to see the level of details that can be built through <code>ocaml-ctypes</code> using their provided primitives. Ultimately, the binding is very clean and elegant, with very few low-level assumptions.</p> +<h1>Conclusion</h1> +<p>It’s been a fun time working on this binding! It’s amazing to see the level of details that can be built through <code>ocaml-ctypes</code> using their provided primitives. Ultimately, the binding is very clean and elegant, with very few low-level assumptions.</p> <p>Likewise, the simplicity and power of the <code>dune</code> build system makes this very fluid to build. Without it, each of the described steps above would have been much more painful to execute and compile.</p> -<p>[1]: My bet is that, at the time the POSIX specifications were being written, there we already several inconsistent <code>socket.h</code> headers out in the wild among the various historical UNIX flavors..</p> +<p>[1]: My bet is that, at the time the POSIX specifications were being written, there we already several inconsistent <code>socket.h</code> headers out in the wild among the various historical UNIX flavors…</p> </div> diff --git a/2024/09/15/肩周炎和肩袖损伤的区别/index.html b/2024/09/15/肩周炎和肩袖损伤的区别/index.html index 1c666b0b..16e591a2 100644 --- a/2024/09/15/肩周炎和肩袖损伤的区别/index.html +++ b/2024/09/15/肩周炎和肩袖损伤的区别/index.html @@ -204,15 +204,20 @@ <p>肩袖损伤是由退行性病变或外力等导致肩袖的4块肌肉、肌腱发生病变，进而导致肩关节局部疼痛、活动受限的疾病。</p> <p>许多肩袖损伤患者无明确的外伤史，而是由长期做过顶运动、提重物或上肢长期固定于一个姿势引起的。</p> <ul> -<li><p>肩周炎的疼痛范围广，涉及整个肩关节，肩袖损伤引起的疼痛多出现在肩前方、外上方</p> +<li> +<p>肩周炎的疼痛范围广，涉及整个肩关节，肩袖损伤引起的疼痛多出现在肩前方、外上方</p> </li> -<li><p>肩周炎的压痛点多而广，肩袖损的伤压痛点多出现在肩前方、上方及肩胛骨外侧缘。</p> +<li> +<p>肩周炎的压痛点多而广，肩袖损的伤压痛点多出现在肩前方、上方及肩胛骨外侧缘。</p> </li> -<li><p>肩周炎患者对气候变化较为敏感，肩袖损伤患者对气候变化不敏感，对劳累、提重物及做过顶运动较为敏感。</p> +<li> +<p>肩周炎患者对气候变化较为敏感，肩袖损伤患者对气候变化不敏感，对劳累、提重物及做过顶运动较为敏感。</p> </li> -<li><p>肩周炎患者活动受限范围广，肩袖损伤患者多以肩关节外展活动受限为主，同时伴有外展无力。</p> +<li> +<p>肩周炎患者活动受限范围广，肩袖损伤患者多以肩关节外展活动受限为主，同时伴有外展无力。</p> </li> -<li><p>肩周炎患者进行上举过顶运动训练后活动范围会好转，症状会减轻；而肩袖损伤患者进行上举过顶运动训练后疼痛加重。</p> +<li> +<p>肩周炎患者进行上举过顶运动训练后活动范围会好转，症状会减轻；而肩袖损伤患者进行上举过顶运动训练后疼痛加重。</p> </li> </ul> |