remote.mli (8645B)
1 (* Unison file synchronizer: src/remote.mli *) 2 (* Copyright 1999-2020, Benjamin C. Pierce (see COPYING for details) *) 3 4 module Thread : sig 5 val unwindProtect : (unit -> 'a Lwt.t) -> (exn -> unit Lwt.t) -> 'a Lwt.t 6 end 7 8 (* A pair of functions enabling conversion from type 'a to a 2.51-compatible 9 type and the other way around. 10 The conversion functions are needed because the 2.51-compatible types must 11 be frozen in time and never changed in future. Type 'a can and will change 12 in time as enhancements are added and old code is removed. 13 When a type is changed, breaking compatibility with 2.51, then respective 14 conversion functions must also be added. *) 15 type 'a convV0Fun 16 val makeConvV0FunArg : 17 ('a -> 'compat) 18 -> ('compat -> 'a) 19 -> 'a convV0Fun * 'b convV0Fun 20 val makeConvV0FunRet : 21 ('b -> 'compat) 22 -> ('compat -> 'b) 23 -> 'a convV0Fun * 'b convV0Fun 24 val makeConvV0Funs : 25 ('a -> 'compata) 26 -> ('compata -> 'a) 27 -> ('b -> 'compatb) 28 -> ('compatb -> 'b) 29 -> 'a convV0Fun * 'b convV0Fun 30 31 (* Register a server function. The result is a function that takes a host 32 name as argument and either executes locally or else communicates with a 33 remote server, as appropriate. (Calling registerServerCmd also has the 34 side effect of registering the command under the given name, so that when 35 we are running as a server it can be looked up and executed when 36 requested by a remote client.) *) 37 (* It is not recommended to use this function in new code unless the cmd is 38 truly independent of any roots/replicas. Use [registerRootCmd] or one of 39 the other functions instead. *) 40 val registerHostCmd : 41 string (* command name *) 42 -> ?convV0: 'a convV0Fun * 'b convV0Fun 43 (* 2.51-compatibility functions for args and result *) 44 -> 'a Umarshal.t -> 'b Umarshal.t 45 -> ('a -> 'b Lwt.t) (* local command *) 46 -> ( Common.root (* -> host (the root path is ignored) *) 47 -> 'a (* arguments *) 48 -> 'b Lwt.t) (* -> (suspended) result *) 49 50 (* A variant of registerHostCmd, for constructing a remote command to be 51 applied to a particular root (host + fspath). 52 - 53 54 A naming convention: when a `root command' is built from a 55 corresponding `local command', we name the two functions 56 <funcName>OnRoot and <funcName>Local *) 57 val registerRootCmd : 58 string (* command name *) 59 -> ?convV0: (Fspath.t * 'a) convV0Fun * 'b convV0Fun 60 (* 2.51-compatibility functions for args 61 and result *) 62 -> 'a Umarshal.t -> 'b Umarshal.t 63 -> ((Fspath.t * 'a) -> 'b Lwt.t) (* local command *) 64 -> ( Common.root (* -> root *) 65 -> 'a (* additional arguments *) 66 -> 'b Lwt.t) (* -> (suspended) result *) 67 68 (* Test whether a command exits on some root *) 69 val commandAvailable : 70 Common.root -> (* root *) 71 string -> (* command name *) 72 bool Lwt.t 73 74 (* Enter "server mode", reading and processing commands from a remote 75 client process until killed *) 76 val beAServer : unit -> unit 77 val waitOnPort : string list -> string -> unit 78 79 (* Whether the server should be killed when the client terminates *) 80 val killServer : bool Prefs.t 81 82 (* Establish a connection to the remote server (if any) corresponding 83 to the root and return the canonical name of the root *) 84 val canonizeRoot : 85 string -> Clroot.clroot -> (string -> Terminal.termInteract) option -> 86 Common.root Lwt.t 87 88 (* Test if connection to the remote server (if any) corresponding 89 to the root is established. Always returns true for local roots *) 90 val isRootConnected : Common.root -> bool 91 92 (* Close the connection to server and run all cleanup and [at_conn_close] 93 handlers. Can also be called for a local root; in this case only the 94 cleanup and [at_conn_close] handlers are run (as there is no connection 95 to close). *) 96 val clientCloseRootConnection : Common.root -> unit 97 98 (* Statistics *) 99 val emittedBytes : float ref 100 val receivedBytes : float ref 101 102 (* Establish a connection to the server. 103 First call openConnectionStart, then loop: 104 call openConnectionPrompt, if you get a prompt, 105 respond with openConnectionReply if desired. 106 After you get None from openConnectionPrompt, 107 call openConnectionEnd. 108 Call openConnectionCancel to abort the connection. 109 *) 110 type preconnection 111 val openConnectionStart : Clroot.clroot -> preconnection option 112 val openConnectionPrompt : preconnection -> string option 113 val openConnectionReply : preconnection -> string -> unit 114 val openConnectionEnd : preconnection -> unit 115 val openConnectionCancel : preconnection -> unit 116 117 (* return the canonical name of the root. The connection 118 to the root must have already been established by 119 the openConnection sequence. *) 120 val canonize : Clroot.clroot -> Common.root 121 122 (****) 123 124 type msgId = int 125 module MsgIdMap : Map.S with type key = msgId 126 val newMsgId : unit -> msgId 127 128 type connection 129 val connectionVersion : connection -> int 130 val connectionOfRoot : Common.root -> connection 131 132 val registerServerCmd : 133 string 134 -> ?convV0: 'a convV0Fun * 'b convV0Fun 135 -> 'a Umarshal.t -> 'b Umarshal.t 136 -> (connection -> 'a -> 'b Lwt.t) 137 -> connection -> 'a -> 'b Lwt.t 138 val intSize : int 139 val encodeInt : int -> Bytearray.t * int * int 140 val decodeInt : Bytearray.t -> int -> int 141 val registerRootCmdWithConnection : 142 string (* command name *) 143 -> ?convV0: 'a convV0Fun * 'b convV0Fun 144 (* 2.51-compatibility functions for args 145 and result *) 146 -> 'a Umarshal.t -> 'b Umarshal.t 147 -> (connection -> 'a -> 'b Lwt.t) (* local command *) 148 -> Common.root (* root on which the command is executed *) 149 -> Common.root (* other root *) 150 -> 'a (* additional arguments *) 151 -> 'b Lwt.t (* result *) 152 153 val streamingActivated : bool Prefs.t 154 155 val registerStreamCmd : 156 string -> 157 (connection -> 'a -> 158 (Bytearray.t * int * int) list -> (Bytearray.t * int * int) list * int) * 159 (connection -> Bytearray.t -> int -> 'a) -> 160 (connection -> 'a -> unit) -> 161 connection -> (('a -> unit Lwt.t) -> 'b Lwt.t) -> 'b Lwt.t 162 163 (* Register a function to be run when the connection between client and server 164 is closed (willingly or unexpectedly). The function should not raise 165 exceptions. If it does then running some of the other registered functions 166 may be skipped (which may not be an issue as the exception is likely going 167 to quit the process). 168 169 Registered functions are only expected to be useful when the connection is 170 closed but the process keeps running (a socket server, for example). Do not 171 use it as a substitute for [at_exit]. 172 173 These functions are additionally run when "closing" a local sync when there 174 is no actual connection. 175 176 Keep in mind that a function registered like this can be called immediately 177 when a lost connection is detected, before any exception indicating lost 178 connection is raised. *) 179 val at_conn_close : ?only_server:bool -> (unit -> unit) -> unit 180 181 (* Register resources to be cleaned up when the connection between client and 182 server closes (normally or exceptionally). This cleanup is additionally run 183 when "closing" a local sync when there is no actual connection. 184 185 Closing the resources is still the responsibility of the code opening the 186 resources but it is not always possible to run the resource cleanup code 187 (due to an Lwt thread being stopped, for example). In those cases the 188 registered resources are cleaned up when the connection is closed, as a 189 last resort. 190 191 The returned functions must be used to track the resources registered for 192 cleanup. *) 193 type ('a, 'b, 'c) resourceC = 194 { register : 'a -> 'a; (* Register an opened resource for cleanup *) 195 release : 'a -> 'b; (* Unregister and close the resource normally *) 196 release_noerr : 'a -> 'c } (* Same as above; don't raise exceptions *) 197 198 val resourceWithConnCleanup : 199 ('a -> 'b) (* Function to close the resource normally *) 200 -> ('a -> 'c) (* Function to close the resource, don't raise exceptions *) 201 -> ('a, 'b, 'c) resourceC (* Functions to track resources for cleanup *) 202 203 (* Make an [Lwt_util.region] which is automatically purged and reset when 204 the connection between client and server closes. This cleanup is also 205 run when "closing" a local sync when there is no actual connection. *) 206 val lwtRegionWithConnCleanup : int -> Lwt_util.region ref