moonbridge
changeset 114:0eba766e9be2
Updated reference to include listeners and local sockets
author | jbe |
---|---|
date | Thu Apr 09 20:02:43 2015 +0200 (2015-04-09) |
parents | 113185a57b06 |
children | 7014436d88ea |
files | reference.txt |
line diff
1.1 --- a/reference.txt Thu Apr 09 19:02:43 2015 +0200 1.2 +++ b/reference.txt Thu Apr 09 20:02:43 2015 +0200 1.3 @@ -74,7 +74,7 @@ 1.4 then true is returned. 1.5 1.6 In case of an I/O error, nil (as first return value) plus an error message (as 1.7 -second result value) are returned. 1.8 +second return value) are returned. 1.9 1.10 1.11 ### socket:drain_nb(maxlen, terminator) 1.12 @@ -84,7 +84,7 @@ 1.13 encountered, then true is returned. 1.14 1.15 In case of an I/O error, nil (as first return value) plus an error message (as 1.16 -second result value) are returned. 1.17 +second return value) are returned. 1.18 1.19 1.20 ### socket:finish() 1.21 @@ -104,7 +104,7 @@ 1.22 data is passed to the operating system). 1.23 1.24 In case of an I/O error, nil (as first return value) plus an error message (as 1.25 -second result value) are returned. On success, the socket userdata object is 1.26 +second return value) are returned. On success, the socket userdata object is 1.27 returned. 1.28 1.29 1.30 @@ -116,7 +116,7 @@ 1.31 if all data could be flushed out. 1.32 1.33 In case of an I/O error, nil (as first return value) plus an error message (as 1.34 -second result value) are returned. 1.35 +second return value) are returned. 1.36 1.37 1.38 ### socket.interval 1.39 @@ -152,7 +152,7 @@ 1.40 return value) plus a notice string (as second return value) are returned. 1.41 1.42 In case of an I/O error, nil (as first return value) plus an error message (as 1.43 -second result value) are returned. 1.44 +second return value) are returned. 1.45 1.46 1.47 ### socket:read_nb(maxlen, terminator) 1.48 @@ -169,7 +169,7 @@ 1.49 string is returned. 1.50 1.51 In case of an I/O error, nil (as first return value) plus an error message (as 1.52 -second result value) are returned. 1.53 +second return value) are returned. 1.54 1.55 1.56 ### socket.remote_ip4 1.57 @@ -194,8 +194,8 @@ 1.58 Alias for socket:close(0). Closes the socket connection by sending a TCP RST 1.59 packet if possible to indicate error condition. 1.60 1.61 -Returns true on success, or nil (as first result value) plus error message (as 1.62 -second result value) in case of an I/O error. Using this method on sockets that 1.63 +Returns true on success, or nil (as first return value) plus error message (as 1.64 +second return value) in case of an I/O error. Using this method on sockets that 1.65 have already been closed (or reset) will throw an error. 1.66 1.67 Warning: Previously sent (and flushed) data may be lost during transmission. 1.68 @@ -208,7 +208,7 @@ 1.69 socket:flush(), socket:finish(), or socket:close(). 1.70 1.71 In case of an I/O error, nil (as first return value) plus an error message (as 1.72 -second result value) are returned. On success, the socket userdata object is 1.73 +second return value) are returned. On success, the socket userdata object is 1.74 returned. 1.75 1.76 1.77 @@ -225,7 +225,7 @@ 1.78 indicates the number of bytes currently in the buffer. 1.79 1.80 In case of an I/O error, nil (as first return value) plus an error message (as 1.81 -second result value) are returned. 1.82 +second return value) are returned. 1.83 1.84 1.85 1.86 @@ -235,6 +235,60 @@ 1.87 The Moonbridge Network Server for Lua Applications comes with its own I/O 1.88 library to support blocking as well as nonblocking I/O operations. 1.89 1.90 +All methods on an I/O handle (e.g. socket) are described in the previous 1.91 +section regarding the "socket" object. All other functions of the library are 1.92 +listed below. 1.93 + 1.94 + 1.95 +### moonbridge_io.localconnect(path) 1.96 + 1.97 +Tries to connect to a local socket (also known as Unix Domain Socket). Returns 1.98 +a socket object on success, or nil (as first return value) plus an error 1.99 +message (as second return value) in case of error. 1.100 + 1.101 + 1.102 +### moonbridge_io.localconnect_nb(path) 1.103 + 1.104 +Tries to connect to a local socket (also known as Unix Domain Socket). Returns 1.105 +a socket object on success, or nil (as first return value) plus an error 1.106 +message (as second return value) in case of error. 1.107 + 1.108 +Same as moonbridge_io.localconnect(path), except that this function does not 1.109 +block and immediately returns a socket object. 1.110 + 1.111 +In case of an I/O error, nil (as first return value) plus an error message (as 1.112 +second return value) may be returned. However, connection errors may also be 1.113 +reported on first read or write on the socket. 1.114 + 1.115 + 1.116 +### moonbridge_io.locallisten(path) 1.117 + 1.118 +Attempts to create a local socket (also known as Unix Domain Socket) to accept 1.119 +incoming connections. 1.120 + 1.121 +Note: The caller is responsible for unlinking the socket in the filesystem 1.122 +before opening or after closing the listening socket. If a file (or socket) 1.123 +already exists at the given path, this function returns with an I/O error. 1.124 + 1.125 +In case of an I/O error, nil (as first return value) plus an error message (as 1.126 +second return value) may be returned.On success, a listener object is returned 1.127 +which supports the methods :accept(), :accept_nb(), and :close(). 1.128 + 1.129 +The method :accept() blocks until a new incoming connection is available in 1.130 +which case a socket object is returned. 1.131 + 1.132 +The method :accept_nb() works like :accept(), except that the call is 1.133 +nonblocking and returns false (plus a notice as second return value) in case no 1.134 +incoming connection is available. It is possible to wait for an incoming 1.135 +connection by including the listener object in the input_set of the 1.136 +moonbridge_io.poll(...) call. 1.137 + 1.138 +The method :close() will close the listening socket. In case of local sockets 1.139 +(Unix Domain Sockets), the socket will not be unlinked in the file system. 1.140 + 1.141 +I/O errors by the methods of the listener object are also reported by returning 1.142 +nil (as first return value) plus an error message (as second return value). 1.143 + 1.144 1.145 ### moonbridge_io.poll(input_set, output_set, timeout) 1.146 1.147 @@ -252,8 +306,8 @@ 1.148 ### moonbridge_io.tcpconnect(hostname, port) 1.149 1.150 Tries to open a TCP connection with the given host and TCP port number. Returns 1.151 -a socket object on success (methods see above), or nil (as first return value) 1.152 -plus an error message (as second return value) in case of error. 1.153 +a socket object on success, or nil (as first return value) plus an error 1.154 +message (as second return value) in case of error. 1.155 1.156 1.157 ### moonbridge_io.tcpconnect_nb(hostname, port) 1.158 @@ -265,10 +319,23 @@ 1.159 numeric IP address as hostname to be truly nonblocking. 1.160 1.161 In case of an I/O error, nil (as first return value) plus an error message (as 1.162 -second result value) may be returned. However, connection errors may also be 1.163 +second return value) may be returned. However, connection errors may also be 1.164 reported on first read or write on the socket. 1.165 1.166 1.167 +### moonbridge_io.tcplisten(hostname, port) 1.168 + 1.169 +Attempts to open a TCP port for listening. To listen on the loopback interface, 1.170 +use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if 1.171 +IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or 1.172 +"0.0.0.0" (IPv4) respectively. 1.173 + 1.174 +In case of an I/O error, nil (as first return value) plus an error message (as 1.175 +second return value) may be returned. On success, a listener object is returned 1.176 +which supports the methods :accept(), :accept_nb(), and :close(). See reference 1.177 +for moonbridge.io_locallisten(...). 1.178 + 1.179 + 1.180 1.181 HTTP module 1.182 -----------