From ef91c5be5f1f07f291a98767d1415d692eb8e0d5 Mon Sep 17 00:00:00 2001 From: Thomas Gazagnaire Date: Sun, 29 Nov 2020 12:07:51 +0100 Subject: [PATCH] Format comments --- .ocamlformat | 1 - src/async/conduit_async.mli | 16 +- src/core/conduit.ml | 4 +- src/core/conduit_intf.ml | 259 +++++++++++++++--------------- src/core/endpoint.mli | 18 +-- src/lwt-ssl/conduit_lwt_ssl.mli | 19 +-- src/lwt-tls/conduit_lwt_tls.mli | 4 +- src/lwt/conduit_lwt.mli | 54 +++---- src/mirage/conduit_mirage_dns.mli | 4 +- 9 files changed, 189 insertions(+), 190 deletions(-) diff --git a/.ocamlformat b/.ocamlformat index e7aa0a4a..d53ab6be 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -6,4 +6,3 @@ nested-match=align sequence-style=separator break-before-in=auto if-then-else=keyword-first -parse-docstrings=false diff --git a/src/async/conduit_async.mli b/src/async/conduit_async.mli index 8fdb2cab..ad1e1cf3 100644 --- a/src/async/conduit_async.mli +++ b/src/async/conduit_async.mli @@ -19,18 +19,16 @@ val serve : service:('cfg, 't, 'v) service -> 'cfg -> unit Async.Condition.t * (unit -> unit Async.Deferred.t) -(** [serve ~handler ~service cfg] creates an usual infinite [service] - loop from the given configuration ['cfg]. It returns the {i promise} - to launch the loop and a condition variable to stop the loop. +(** [serve ~handler ~service cfg] creates an usual infinite [service] loop from + the given configuration ['cfg]. It returns the {i promise} to launch the + loop and a condition variable to stop the loop. {[ - let stop, loop = serve - ~handler ~service:TCP.service cfg in - Async_unix.Signal.handle [ Core.Signal.int ] - ~f:(fun _sig -> Async.Condition.broadcast stop ()) ; + let stop, loop = serve ~handler ~service:TCP.service cfg in + Async_unix.Signal.handle [ Core.Signal.int ] ~f:(fun _sig -> + Async.Condition.broadcast stop ()) ; loop () - ]} -*) + ]} *) val reader_and_writer_of_flow : flow -> (Async.Reader.t * Async.Writer.t) Async.Deferred.t diff --git a/src/core/conduit.ml b/src/core/conduit.ml index 212a51bf..9d9d747d 100644 --- a/src/core/conduit.ml +++ b/src/core/conduit.ml @@ -28,8 +28,8 @@ module Log = (val Logs.src_log src : Logs.LOG) type ('a, 'b, 'c) thd = | Thd : 'b -> ('a, 'b, 'c) thd (** XXX(dinosaure): we must define [(_, _, _) thd] to be able to keep some - existential types (eg. ['cfg] and ['flow] when we use [('cfg, 't, 'flow) - service]) but still to use only on (eg. ['t]). + existential types (eg. ['cfg] and ['flow] when we use + [('cfg, 't, 'flow) service]) but still to use only on (eg. ['t]). We add [warning "-37"] to be able to compile the project. *) diff --git a/src/core/conduit_intf.ml b/src/core/conduit_intf.ml index 2c21478b..4d0f4f18 100644 --- a/src/core/conduit_intf.ml +++ b/src/core/conduit_intf.ml @@ -4,25 +4,27 @@ module type FLOW = sig (** [FLOW] is the signature for flow clients. A [flow] is an abstract value over which I/O functions such as {!send}, - {!recv} and {!close} can be used. + {!recv} and {!close} can be used. {[ - type input = bytes and output = string + type input = bytes + + and output = string + type +'a s = 'a let process flow = let buf = Bytes.create 0x1000 in match Flow.recv flow buf with | Ok (`Input len) -> - let str = Bytes.sub_string buf 0 len in - ignore (Flow.send flow str) + let str = Bytes.sub_string buf 0 len in + ignore (Flow.send flow str) | _ -> failwith "Flow.recv" ]} The given flow can be more complex than a simple TCP flow for example. It - can be wrapped into a TLS layer. However, the goal is to be able to implement - a protocol without such complexity. - *) + can be wrapped into a TLS layer. However, the goal is to be able to + implement a protocol without such complexity. *) type +'a io @@ -31,16 +33,16 @@ module type FLOW = sig (** {3 Input & Output.} Depending on the I/O model, the type for inputs and outputs can differ ; - for instance they could allow users the ability to define capabilities on - them such as {i read} or {i write} capabilities. + for instance they could allow users the ability to define capabilities on + them such as {i read} or {i write} capabilities. However, in most of the current [Conduit] backends: {[ type input = Cstruct.t + type output = Cstruct.t - ]} - *) + ]} *) type input @@ -55,17 +57,17 @@ module type FLOW = sig (** [pp_error] is the pretty-printer for {!error}. *) val recv : flow -> input -> (int or_end_of_flow, error) result io - (** [recv flow input] is [Ok (`Input len)] iff [len] bytes of data has been received from - the flow [flow] and copied in [input]. *) + (** [recv flow input] is [Ok (`Input len)] iff [len] bytes of data has been + received from the flow [flow] and copied in [input]. *) val send : flow -> output -> (int, error) result io (** [send t output] is [Ok len] iff [len] bytes of data from [output] has been - sent over the flow [flow]. *) + sent over the flow [flow]. *) val close : flow -> (unit, error) result io (** [close flow] closes [flow]. Subsequent calls to {!recv} on [flow] will - return [`End_of_flow]. Subsequent calls to {!send} on [t] will return an - [Error]. *) + return [`End_of_flow]. Subsequent calls to {!send} on [t] will return an + [Error]. *) end module type PROTOCOL = sig @@ -131,16 +133,15 @@ module type S = sig type flow = private .. (** The type for generic flows. {!PROTOCOL} implementations are extending (via - {!register}) this type. It allows users to extract the underlying flow - implementation: + {!register}) this type. It allows users to extract the underlying flow + implementation: - {[ - Conduit.connect domain_name >>? function - | Conduit_lwt_unix_tcp.T Conduit.(Value (file_descr : Lwt_unix.file_descr)) -> ... - | Conduit_lwt_unix_tls.T Conduit.(Value (fd, (tls : Tls.Engine.state))) -> ... - | _ -> ... (* use flow functions for the default case *) - ]} - *) + {[ + Conduit.connect domain_name >>? function + | Conduit_lwt_unix_tcp.T Conduit.(Value (file_descr : Lwt_unix.file_descr)) -> ... + | Conduit_lwt_unix_tls.T Conduit.(Value (fd, (tls : Tls.Engine.state))) -> ... + | _ -> ... (* use flow functions for the default case *) + ]} *) type error = [ `Msg of string | `Not_found ] @@ -149,37 +150,38 @@ module type S = sig val recv : flow -> input -> ([ `Input of int | `End_of_flow ], [> error ]) result io (** [recv flow input] is [Ok (`Input len)] iff [n] bytes of data has been - received from the flow [flow] and copied in [input]. *) + received from the flow [flow] and copied in [input]. *) val send : flow -> output -> (int, [> error ]) result io (** [send flow output] is [Ok n] iff [n] bytes of date from [output] has been - sent over the flow [flow]. *) + sent over the flow [flow]. *) val close : flow -> (unit, [> error ]) result io (** [close flow] closes [flow]. Subsequent calls to {!recv} will return - [Ok `End_of_flow]. Subsequent calls to {!send} will return an [Error]. *) + [Ok `End_of_flow]. Subsequent calls to {!send} will return an [Error]. *) (** {2:registration Protocol registration.} *) (** A flow is a system that allows entities to transmit {i payloads}. These - entities do not have to care about the underlying transport mechanism. - flows simply deal with routing and delivering of these payloads. That - abstraction allows these protocols to compose. + entities do not have to care about the underlying transport mechanism. + flows simply deal with routing and delivering of these payloads. That + abstraction allows these protocols to compose. For example, the Transmission Control Protocol (TCP) is representable as a - flow, because it is able to encapsulate some {i payloads} without - interpreting it. A counter-example is the Simple Mail Transfer Protocol - (SMTP) which needs an interpretation of its {i payloads}: tokens such as - [EHLO] or [QUIT] have a direct incidence over the life-cycle of the - connection. + flow, because it is able to encapsulate some {i payloads} without + interpreting it. A counter-example is the Simple Mail Transfer Protocol + (SMTP) which needs an interpretation of its {i payloads}: tokens such as + [EHLO] or [QUIT] have a direct incidence over the life-cycle of the + connection. An other protocol representable as a flow is the Transport Layer Security - (TLS), as it deals only with privacy and data integrity. [Conduit] is able - to compose flows together like [TCP ∘ TLS] to make a new flow. Higher-level - protocols can be built in top of these abstract flows: for instance, Secure - Simple Mail Transfer Protocol (SSMTP) or HyperText Transfer Protocol Secure - (HTTPS) can be defined on top of both TCP and TLS. Using [Conduit], these - can be abstracted to work over any flow implementations. *) + (TLS), as it deals only with privacy and data integrity. [Conduit] is able + to compose flows together like [TCP ∘ TLS] to make a new flow. + Higher-level protocols can be built in top of these abstract flows: for + instance, Secure Simple Mail Transfer Protocol (SSMTP) or HyperText + Transfer Protocol Secure (HTTPS) can be defined on top of both TCP and + TLS. Using [Conduit], these can be abstracted to work over any flow + implementations. *) module type FLOW = FLOW with type input = input @@ -199,18 +201,18 @@ module type S = sig type ('edn, 'flow) protocol (** The type for client protocols. ['edn] is the type for endpoint parameters. - ['flow] is the type for underlying flows. + ['flow] is the type for underlying flows. Endpoints allow users to create flows by either connecting directly to a - remote server or by resolving domain names (with {!connect}). *) + remote server or by resolving domain names (with {!connect}). *) val register : protocol:('edn, 'flow) impl -> ('edn, 'flow) protocol (** [register ~protocol] is the protocol using the implementation [protocol]. - [protocol] must provide a [connect] function to allow client flows to be - created. + [protocol] must provide a [connect] function to allow client flows to be + created. For instance, on Unix, [Conduit] clients will use [Unix.sockaddr] as flow - endpoints, while [Unix.file_descr] would be used for the flow transport. + endpoints, while [Unix.file_descr] would be used for the flow transport. {[ module Conduit_tcp : sig @@ -221,8 +223,8 @@ module type S = sig ]} Client endpoints can of course be more complex, for instance to hold TLS - credentials, and [Conduit] allows all these kinds of flow to be used - transparently: + credentials, and [Conduit] allows all these kinds of flow to be used + transparently: {[ module Conduit_tcp_tls : sig @@ -233,33 +235,32 @@ module type S = sig ]} As a protocol implementer, you must {i register} your implementation and - expose the {i witness} of it. Then, users will be able to use it. *) + expose the {i witness} of it. Then, users will be able to use it. *) (** {2 Injection and Extraction.} The goal of [Conduit] is to provide: - {ul - {- A way to manipulate a fully-abstract [flow].} - {- A way to manipulate a concrete and well-know [flow].}} - [Conduit] provides several mechanisms to be able to manipulate our abstract - type {!flow} and destruct it to a concrete value such as a [Unix.file_descr]. - [Conduit] can assert one assumption: from a given abstracted [flow], it exists - one and only one {!FLOW} implementation. + - A way to manipulate a fully-abstract [flow]. + - A way to manipulate a concrete and well-know [flow]. - As [Conduit] determines this implementation, the user can determine the used - implementation when he wants to {!send} or {!recv} datas. + [Conduit] provides several mechanisms to be able to manipulate our + abstract type {!flow} and destruct it to a concrete value such as a + [Unix.file_descr]. [Conduit] can assert one assumption: from a given + abstracted [flow], it exists one and only one {!FLOW} implementation. + + As [Conduit] determines this implementation, the user can determine the + used implementation when he wants to {!send} or {!recv} datas. So [Conduit] uses or extracts uniqely the implementation registered before - with {!register} and no layer can tweak or update this assertion. + with {!register} and no layer can tweak or update this assertion. {!repr}, {!flow}, {!impl} and {!is} can extracts in differents ways the - abstracted {!flow}: - {ul - {- with the {i pattern-matching}} - {- with {i first-class module}} - {- with the function {!is}}} - *) + abstracted {!flow}: + + - with the {i pattern-matching} + - with {i first-class module} + - with the function {!is} *) module type REPR = sig type t @@ -269,42 +270,43 @@ module type S = sig val repr : ('edn, 'v) protocol -> (module REPR with type t = ('edn, 'v) value) (** As a protocol implementer, you should expose the concrete type of your - flow (to be able users to {i destruct} {!flow}). [repr] returns a module - which contains extension of {!flow} from your [protocol] such as: + flow (to be able users to {i destruct} {!flow}). [repr] returns a module + which contains extension of {!flow} from your [protocol] such as: {[ module Conduit_tcp : sig type t = (Unix.sockaddr, Unix.file_descr) Conduit.value + type Conduit.flow += T of t + val t : (Unix.sockaddr, Unix.file_descr) protocol end = struct let t = register ~protocol:(module TCP) - include (val (Conduit.repr t)) + + include (val Conduit.repr t) end ]} With this interface, users are able to {i destruct} {!flow} to your - concrete type: + concrete type: {[ Conduit.connect domain_name >>? function | Conduit_tcp.T (Conduit.Value file_descr) -> ... | _ -> ... - ]} - *) + ]} *) type unpack = Flow : 'flow * (module FLOW with type flow = 'flow) -> unpack val unpack : flow -> unpack (** [pack flow] projects the module implementation associated to the given - abstract [flow] such as: + abstract [flow] such as: {[ Conduit.connect edn >>= fun flow -> - let Conduit.Flow (flow, (module Flow)) = Conduit.unpack flow in + let (Conduit.Flow (flow, (module Flow))) = Conduit.unpack flow in Flow.send flow "Hello World!" - ]} - *) + ]} *) val impl : ('edn, 'flow) protocol -> @@ -313,44 +315,43 @@ module type S = sig val cast : flow -> (_, 'flow) protocol -> 'flow option (** [cast flow protocol] tries to {i cast} the given [flow] to the concrete - type described by the given [protocol]. + type described by the given [protocol]. {[ match Conduit.is flow Conduit_tcp.t with - | Some (file_descr : Unix.file_descr) -> Some (Unix.getpeername file_descr) + | Some (file_descr : Unix.file_descr) -> + Some (Unix.getpeername file_descr) | None -> None - ]} - *) + ]} *) val pack : (_, 'v) protocol -> 'v -> flow - (** [pack protocol concrete_flow] abstracts the given [flow] into the - {!flow} type from a given [protocol]. It permits to use [Conduit] with a - concrete value created by the user. + (** [pack protocol concrete_flow] abstracts the given [flow] into the {!flow} + type from a given [protocol]. It permits to use [Conduit] with a concrete + value created by the user. {[ let socket = Unix.socket Unix.PF_INET Unix.SOCK_STREAM 0 in let flow = Conduit.pack Conduit_tcp.t socket in Conduit.send flow "Hello World!" - ]} - *) + ]} *) (** {2:resolution Domain name resolvers.} *) type 'edn resolver = Endpoint.t -> 'edn option io (** The type for resolver functions, which resolve domain names to endpoints. - For instance, the DNS resolver function is: - - {[ - let http_resolver : Unix.sockaddr resolver = function - | IP ip -> Some (Ipaddr_unix.to_inet_addr ip, 80) - | Domain domain_name -> match Unix.gethostbyname (Domain_name.to_string domain_name) with - | { Unix.h_addr_list; _ } -> - if Array.length h_addr_list > 0 - then Some (Unix.ADDR_INET (h_addr_list.(0), 80)) - else None - | exception _ -> None - ]} - *) + For instance, the DNS resolver function is: + + {[ + let http_resolver : Unix.sockaddr resolver = function + | IP ip -> Some (Ipaddr_unix.to_inet_addr ip, 80) + | Domain domain_name -> + match Unix.gethostbyname (Domain_name.to_string domain_name) with + | { Unix.h_addr_list; _ } -> + if Array.length h_addr_list > 0 + then Some (Unix.ADDR_INET (h_addr_list.(0), 80)) + else None + | exception _ -> None + ]} *) type resolvers @@ -363,11 +364,11 @@ module type S = sig resolvers -> resolvers (** [add protocol ?priority resolver resolvers] adds a new resolver function - [resolver] to [resolvers]. + [resolver] to [resolvers]. When the [resolver] is able to resolve the given domain name, it will try - to connect to the specified client endpoint. Resolvers are iterated in - priority order (lower to higher). + to connect to the specified client endpoint. Resolvers are iterated in + priority order (lower to higher). {[ let http_resolver = ... @@ -386,9 +387,9 @@ module type S = sig Endpoint.t -> (flow, [> error ]) result io (** [resolve resolvers domain_name] is the flow created by connecting to the - domain name [domain_name], using the resolvers [resolvers]. Each resolver - tries to resolve the given domain-name (they are ordered by the given - priority). The first which connects successfully wins. + domain name [domain_name], using the resolvers [resolvers]. Each resolver + tries to resolve the given domain-name (they are ordered by the given + priority). The first which connects successfully wins. The resolver result is a flow connect to that winning endpoint. @@ -396,7 +397,9 @@ module type S = sig let mirage_io = domain_name_exn "mirage.io" val resolver_on_my_private_network : Unix.sockaddr resolver + val resolver_on_internet : Unix.sockaddr resolver + val resolver_with_tls : (Unix.sockaddr * Tls.Config.client) resolver let resolvers = @@ -405,14 +408,14 @@ module type S = sig |> add tcp ~priority:10 resolver_on_my_private_network |> add tcp ~priority:20 resolver_on_internet - let () = Conduit.resolve resolvers (Conduit.Endpoint.domain mirage_io) >>? function + let () = + Conduit.resolve resolvers (Conduit.Endpoint.domain mirage_io) + >>? function | TCP.T (Conduit.Value file_descr) as flow -> - let peer = Unix.getpeername file_descr in - ignore @@ Conduit.send flow ("Hello " ^ string_of_sockaddr peer) - | flow -> - ignore @@ Conduit.send flow "Hello World!" - ]} - *) + let peer = Unix.getpeername file_descr in + ignore @@ Conduit.send flow ("Hello " ^ string_of_sockaddr peer) + | flow -> ignore @@ Conduit.send flow "Hello World!" + ]} *) val connect : 'edn -> ('edn, _) protocol -> (flow, [> error ]) result io @@ -429,15 +432,15 @@ module type S = sig type ('cfg, 't, 'flow) service (** The type for services, e.g. service-side protocols. ['cfg] is the type - for configuration, ['t] is the type for state states. ['flow] is the type - for underlying flows. *) + for configuration, ['t] is the type for state states. ['flow] is the + type for underlying flows. *) val equal : ('cfg0, 't0, 'flow0) service -> ('cfg1, 't1, 'flow1) service -> (('cfg0, 'cfg1) refl * ('t0, 't1) refl * ('flow0, 'flow1) refl) option - (** [equal svc0 svc1 ] proves that [svc0] and [svc1] are - physically the same. For instance, [Conduit] asserts: + (** [equal svc0 svc1] proves that [svc0] and [svc1] are physically the same. + For instance, [Conduit] asserts: {[ let service = Service.register ~service:(module V) ;; @@ -451,11 +454,12 @@ module type S = sig service:('cfg, 't, 'v) impl -> protocol:(_, 'v) protocol -> ('cfg, 't, 'v) service - (** [register ~service ~protocool] is the service using the implementation [service] - bound with implementation of a [protocol]. [service] must define [make] and [accept] - function to be able to create server-side flows. + (** [register ~service ~protocool] is the service using the implementation + [service] bound with implementation of a [protocol]. [service] must + define [make] and [accept] function to be able to create server-side + flows. - For instance: + For instance: {[ module TCP_service : SERVICE with type configuration = Unix.sockaddr @@ -465,8 +469,7 @@ module type S = sig let tcp_protocol = Conduit.register ~protocol:(module TCP_protocol) let tcp_service : (Unix.sockaddr, Unix.file_descr, Unix.file_descr) Service.service = Conduit.Service.register ~service:(module TCP_service) ~protocol:tcp_protocol - ]} - *) + ]} *) type error = [ `Msg of string ] @@ -474,23 +477,23 @@ module type S = sig val init : 'cfg -> service:('cfg, 't, 'v) service -> ('t, [> error ]) result io - (** [init cfg ~service] initialises the service with the - configuration [cfg]. *) + (** [init cfg ~service] initialises the service with the configuration + [cfg]. *) val accept : service:('cfg, 't, 'v) service -> 't -> (flow, [> error ]) result io (** [accept service t] waits for a connection on the service [t]. The result - is a {i flow} connected to the client. *) + is a {i flow} connected to the client. *) val close : service:('cfg, 't, 'v) service -> 't -> (unit, [> error ]) result io (** [close ~service t] releases the resources associated to the server [t]. *) val pack : (_, _, 'v) service -> 'v -> flow - (** [pack service v] returns the abstracted value [v] as {!pack} does - for a given protocol {i witness} (bound with the given [service]). - It serves to abstract the flow created (and initialised) by the - service to a {!flow}. + (** [pack service v] returns the abstracted value [v] as {!pack} does for a + given protocol {i witness} (bound with the given [service]). It serves + to abstract the flow created (and initialised) by the service to a + {!flow}. {[ let handler (flow : Conduit.flow) = diff --git a/src/core/endpoint.mli b/src/core/endpoint.mli index 59c9fef5..1e9c24f3 100644 --- a/src/core/endpoint.mli +++ b/src/core/endpoint.mli @@ -6,21 +6,19 @@ val pp : Format.formatter -> t -> unit (** Pretty-printer of {!t}. *) val of_string : string -> (t, [> `Msg of string ]) result -(** [of_string str] returns an endpoint from the given [string]. - We tried to parse the given [string] as an {i hostname} and if - it fails, we try to consider it as an IP (V4 or V6). +(** [of_string str] returns an endpoint from the given [string]. We tried to + parse the given [string] as an {i hostname} and if it fails, we try to + consider it as an IP (V4 or V6). - If the given [string] is neither a {i hostname} nor an IP, we - return an error. *) + If the given [string] is neither a {i hostname} nor an IP, we return an + error. *) val v : string -> t -(** An alias of {!of_string}. In the case of an error, we raise - an exception. *) +(** An alias of {!of_string}. In the case of an error, we raise an exception. *) val to_string : t -> string -(** [to_string t] returns a valid string which represents the - endpoint. By {i valid}, we means that the returned [string] - can safely be used with {!v}. *) +(** [to_string t] returns a valid string which represents the endpoint. By + {i valid}, we means that the returned [string] can safely be used with {!v}. *) val domain : [ `host ] Domain_name.t -> t (** [domain domain_name] returns an endpoint from a {i hostname}. *) diff --git a/src/lwt-ssl/conduit_lwt_ssl.mli b/src/lwt-ssl/conduit_lwt_ssl.mli index f2ad0922..adcea331 100644 --- a/src/lwt-ssl/conduit_lwt_ssl.mli +++ b/src/lwt-ssl/conduit_lwt_ssl.mli @@ -1,14 +1,14 @@ -(** Implementation of the SSL support (according [Lwt_ssl]) with - [conduit-lwt]. +(** Implementation of the SSL support (according [Lwt_ssl]) with [conduit-lwt]. This implementation assumes that underlying protocol used to compose with - SSL must deliver a [Lwt_unix.file_descr] - such as [Conduit_lwt.TCP]. - From that, we are able to compose your protocol with [Lwt_ssl] such as: + SSL must deliver a [Lwt_unix.file_descr] - such as [Conduit_lwt.TCP]. From + that, we are able to compose your protocol with [Lwt_ssl] such as: {[ let ssl_protocol = protocol_with_ssl TCP.protocol - let ssl_service = service_with_ssl TCP.service - ~file_descr:TCP.file_descr ssl_protocol + + let ssl_service = + service_with_ssl TCP.service ~file_descr:TCP.file_descr ssl_protocol ]} Then, TCP + SSL is available as any others [conduit] protocols or services @@ -23,7 +23,8 @@ {b NOTE}: [verify] is called after a call to [flow] (which should do the [connect] call). So, nothing was exchanged between you and your peer at this time - even the handshake. It permits to fill the SSL socket with some - information such as the hostname of the peer with [Ssl.set_client_SNI_hostname]. *) + information such as the hostname of the peer with + [Ssl.set_client_SNI_hostname]. *) open Conduit_lwt @@ -49,8 +50,8 @@ val endpoint : [Lwt_unix.file_descr] from it. [verify] is the function called just after the initialization of the - underlying ['flow]. It permits to request a verification such as the {i - hostname} with your peer. *) + underlying ['flow]. It permits to request a verification such as the + {i hostname} with your peer. *) val protocol_with_ssl : ('edn, 'flow) protocol -> (('edn, 'flow) endpoint, Lwt_ssl.socket) protocol diff --git a/src/lwt-tls/conduit_lwt_tls.mli b/src/lwt-tls/conduit_lwt_tls.mli index 56a21c78..9e8c554d 100644 --- a/src/lwt-tls/conduit_lwt_tls.mli +++ b/src/lwt-tls/conduit_lwt_tls.mli @@ -2,8 +2,8 @@ [conduit-lwt]. This implementation is a {i specialization} of [conduit-tls] with - [conduit-lwt]. Underlying protocol or service can be anything into the - scope of [conduit-lwt]. + [conduit-lwt]. Underlying protocol or service can be anything into the scope + of [conduit-lwt]. For more details about behaviours, you should look into [conduit-tls]. *) diff --git a/src/lwt/conduit_lwt.mli b/src/lwt/conduit_lwt.mli index a42ba0f3..4a035685 100644 --- a/src/lwt/conduit_lwt.mli +++ b/src/lwt/conduit_lwt.mli @@ -8,16 +8,16 @@ include val io_of_flow : flow -> Lwt_io.input Lwt_io.channel * Lwt_io.output Lwt_io.channel -(** [io_of_flow flow] creates an input flow and an output flow according - to [Lwt_io]. This function, even if it creates something more usable - is {b deprecated}. Indeed, [Lwt_io] has its own way to schedule [read] - and [write] - you should be aware about that more specially when you - use [Conduit_tls] or [Conduit_lwt_ssl]. +(** [io_of_flow flow] creates an input flow and an output flow according to + [Lwt_io]. This function, even if it creates something more usable is + {b deprecated}. Indeed, [Lwt_io] has its own way to schedule [read] and + [write] - you should be aware about that more specially when you use + [Conduit_tls] or [Conduit_lwt_ssl]. Due to a specific behavior, [Lwt_io] does not fit with some specific - protocols - non thread-safe protocols, {i send-first} protocols, etc. - From these reasons, and even if {!TCP} try to the best to fit under - an [Lwt_io], you should not use this function. *) + protocols - non thread-safe protocols, {i send-first} protocols, etc. From + these reasons, and even if {!TCP} try to the best to fit under an [Lwt_io], + you should not use this function. *) type ('a, 'b, 'c) service = ('a, 'b, 'c) Service.service (** The type for lwt services. *) @@ -28,22 +28,21 @@ val serve : service:('cfg, 'service, 'v) service -> 'cfg -> unit Lwt_condition.t * (unit -> unit Lwt.t) -(** [serve ~handler ~service cfg] creates an usual infinite [service] - loop from the given configuration ['cfg]. It returns the {i promise} to launch - the loop and a condition variable to stop the loop. +(** [serve ~handler ~service cfg] creates an usual infinite [service] loop from + the given configuration ['cfg]. It returns the {i promise} to launch the + loop and a condition variable to stop the loop. {[ - let stop, loop = serve - ~handler ~service:TCP.service cfg in + let stop, loop = serve ~handler ~service:TCP.service cfg in Lwt.both - (Lwt_unix.sleep 10. >>= fun () -> - Lwt_condition.broadcast stop () ; - Lwt.return ()) + ( Lwt_unix.sleep 10. >>= fun () -> + Lwt_condition.broadcast stop () ; + Lwt.return () ) (loop ()) ]} - In your example, we want to launch a server only for 10 seconds. To help the user, - the option [?timeout] allows us to wait less than [timeout] seconds. *) + In your example, we want to launch a server only for 10 seconds. To help the + user, the option [?timeout] allows us to wait less than [timeout] seconds. *) module TCP : sig (** Implementation of TCP protocol as a client. @@ -51,15 +50,15 @@ module TCP : sig Behaviours of [Protocol] differs from {i syscall} provided by [Lwt_unix]. This is a description of what they currently do. - {b NOTE}: [recv] wants to fill the given buffer as much as possible until it - has reached {i end-of-input}. In other words, [recv] can do a multiple call - to [Lwt_unix.recv] to fill the given buffer. + {b NOTE}: [recv] wants to fill the given buffer as much as possible until + it has reached {i end-of-input}. In other words, [recv] can do a multiple + call to [Lwt_unix.recv] to fill the given buffer. - {b NOTE}: [send] tries to send as much as it can the given buffer. However, - if internal call of [Lwt_unix.send] returns something smaller than what we - requested, we stop the process and return how many byte(s) we sended. In - other word, [send] can do a multiple call to [Lwt_unix.send] until we fully - sended what we wanted. *) + {b NOTE}: [send] tries to send as much as it can the given buffer. + However, if internal call of [Lwt_unix.send] returns something smaller + than what we requested, we stop the process and return how many byte(s) we + sended. In other word, [send] can do a multiple call to [Lwt_unix.send] + until we fully sended what we wanted. *) module Protocol : sig include @@ -83,7 +82,8 @@ module TCP : sig communicate over TCP. *) val peer : flow -> Unix.sockaddr - (** [peer flow] retunrs the address of the peer connected to the given [flow]. *) + (** [peer flow] retunrs the address of the peer connected to the given + [flow]. *) val sock : flow -> Unix.sockaddr (** [sock flow] returns the current addres to which the socket is bound. *) diff --git a/src/mirage/conduit_mirage_dns.mli b/src/mirage/conduit_mirage_dns.mli index 73246255..f63fb17c 100644 --- a/src/mirage/conduit_mirage_dns.mli +++ b/src/mirage/conduit_mirage_dns.mli @@ -1,5 +1,5 @@ -(** MirageOS-functor to be able to resolve a domain-name - such as [gethostbyname] with [ocaml-dns]. *) +(** MirageOS-functor to be able to resolve a domain-name such as [gethostbyname] + with [ocaml-dns]. *) module Make (R : Mirage_random.S)