moonbridge
changeset 91:6b26783f9323
write_nb returns total number of bytes buffered in case of block; Updated reference
author | jbe |
---|---|
date | Tue Apr 07 03:50:28 2015 +0200 (2015-04-07) |
parents | 54e6104c70a6 |
children | 111b2469b753 |
files | moonbridge_io.c reference.txt |
line diff
1.1 --- a/moonbridge_io.c Tue Apr 07 02:52:41 2015 +0200 1.2 +++ b/moonbridge_io.c Tue Apr 07 03:50:28 2015 +0200 1.3 @@ -268,13 +268,12 @@ 1.4 handle->writebufcnt = 0; 1.5 if (nonblocking) lua_pushinteger(L, 0); 1.6 } else { 1.7 - if (nonblocking) lua_pushinteger(L, handle->writeleft - handle->writebufcnt); 1.8 + if (nonblocking) lua_pushinteger(L, handle->writeleft); 1.9 } 1.10 if (!nonblocking) lua_pushvalue(L, 1); 1.11 return 1; 1.12 moonbr_io_write_impl_block: 1.13 - if (flush) lua_pushinteger(L, handle->writeleft); 1.14 - else lua_pushinteger(L, handle->writeleft - handle->writebufcnt); 1.15 + lua_pushinteger(L, handle->writeleft); 1.16 return 1; 1.17 } 1.18
2.1 --- a/reference.txt Tue Apr 07 02:52:41 2015 +0200 2.2 +++ b/reference.txt Tue Apr 07 03:50:28 2015 +0200 2.3 @@ -52,42 +52,65 @@ 2.4 a single socket object as argument, which is described below: 2.5 2.6 2.7 -### socket:cancel() 2.8 - 2.9 -Closes the socket connection by sending a TCP RST package if possible to 2.10 -indicate error condition. Returns true on success, or nil plus error message in 2.11 -case of an I/O error. Using this method on sockets that have already been 2.12 -closed (or canceled) will throw an error. 2.13 - 2.14 -Warning: Previously sent (and flushed) data may be lost during transmission. 2.15 - 2.16 - 2.17 ### socket:close(timeout) 2.18 2.19 Closes the socket connection (input and output stream) by flushing all data and 2.20 -sending a TCP FIN package. Returns true on success, or nil plus error message 2.21 -in case of an I/O error. Using this method on sockets that have already been 2.22 -closed (or canceled) will throw an error. 2.23 +sending a TCP FIN packet. If the timeout value is non-nil but zero, a TCP RST 2.24 +is sent instead. If a positive timeout value is given and if the remote peer 2.25 +doesn't respond with a TCP FIN within the given time, a TCP RST is sent in 2.26 +addition to the previously sent TCP FIN packet. If the timeout value is nil or 2.27 +negative, the call returns immediately and the operating system will wait for 2.28 +the peer's TCP FIN packet. 2.29 + 2.30 +Returns true on success, or nil plus error message in case of an I/O error. 2.31 +Using this method on sockets that have already been closed (or reset) will 2.32 +throw an error. 2.33 2.34 Warning: Pending data on the input stream may cause connection aborts (TCP RST) 2.35 depending on the particular operating system used. All pending input data 2.36 -should have been read before calling socket:close(). 2.37 +should have been read (or drained) before calling socket:close(). 2.38 + 2.39 + 2.40 +### socket:drain(maxlen, terminator) 2.41 2.42 -The optional timeout parameter may be used to wait until all data has been sent 2.43 -out, or until the timeout elapses (in which case a TCP RST is sent) whichever 2.44 -happens first. A timeout value of 0 or nil causes immediate return and sending 2.45 -of pending data in background (recommended). 2.46 +Same as socket:read(maxlen, terminator), but discards the input and returns the 2.47 +number of discarded bytes. If no bytes could be read but EOF was encountered, 2.48 +then true is returned. 2.49 + 2.50 +In case of an I/O error, nil (as first return value) plus an error message (as 2.51 +second result value) are returned. 2.52 2.53 2.54 -### socket:flush() 2.55 +### socket:drain_nb(maxlen, terminator) 2.56 2.57 -Alias for socket.output:flush() 2.58 +Same as socket:read_nb(maxlen, terminator), but discards the input and returns 2.59 +the number of discarded bytes. If no bytes could be read but EOF was 2.60 +encountered, then true is returned. 2.61 + 2.62 +In case of an I/O error, nil (as first return value) plus an error message (as 2.63 +second result value) are returned. 2.64 + 2.65 2.66 2.67 -### socket.input 2.68 +### socket:flush(...) 2.69 + 2.70 +Same as socket:write(...) but additionally flushes the socket (i.e. all pending 2.71 +data is passed to the operating system). 2.72 + 2.73 +In case of an I/O error, nil (as first return value) plus an error message (as 2.74 +second result value) are returned. On success, the socket userdata object is 2.75 +returned. 2.76 + 2.77 2.78 -Lua file handle representing the input stream of the socket connection. 2.79 -Supports the same methods as io.open()'s return values. 2.80 +### socket:flush_nb(...) 2.81 + 2.82 +Same as socket:write_nb(...) but additionally flushes the socket (i.e. all 2.83 +pending data is passed to the operating system). The total number of bytes that 2.84 +could not be passed yet to the operating system is returned. Zero is returned 2.85 +if all data could be flushed out. 2.86 + 2.87 +In case of an I/O error, nil (as first return value) plus an error message (as 2.88 +second result value) are returned. 2.89 2.90 2.91 ### socket.interval 2.92 @@ -96,11 +119,6 @@ 2.93 an elapsed interval timer. Otherwise nil. 2.94 2.95 2.96 -### socket:lines() 2.97 - 2.98 -Alias for socket.input:lines() 2.99 - 2.100 - 2.101 ### socket.local_ip4 2.102 2.103 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a 2.104 @@ -118,27 +136,34 @@ 2.105 Local TCP port used for the connection. 2.106 2.107 2.108 -### socket.output 2.109 +### socket:read(maxlen, terminator) 2.110 2.111 -Lua file handle representing the output stream of the socket connection. 2.112 -Supports the same methods as io.open()'s return values. 2.113 +Read up to maxlen bytes or until an optional termination character is 2.114 +encountered (which is included in the result). The maxlen value may be nil, in 2.115 +which case there is no limit on the number of bytes read. 2.116 2.117 +If EOF is encountered before any data could be read, then false (as first 2.118 +return value) plus a notice string (as second return value) are returned. 2.119 2.120 -### socket:read(...) 2.121 - 2.122 -Alias for socket.input:read() 2.123 +In case of an I/O error, nil (as first return value) plus an error message (as 2.124 +second result value) are returned. 2.125 2.126 2.127 -### socket:readuntil(terminator, maxlen) 2.128 +### socket:read_nb(maxlen, terminator) 2.129 + 2.130 +Read up to maxlen bytes, until an optional termination character is encountered 2.131 +(which is included in the result), or until no more data is available for 2.132 +reading. The maxlen value may be nil, in which case there is no limit on the 2.133 +number of bytes read. 2.134 2.135 -Reads as many bytes until a byte equal to the terminator value occurs. An 2.136 -optional maximum length may be specified. The terminating byte is included in 2.137 -the return value (unless the maximum length would be exceeded). On EOF, nil is 2.138 -returned. In case of an I/O error, nil (as first result value) plus an error 2.139 -message (as second result value) is returned. 2.140 +If EOF is encountered before any data could be read, then false (as first 2.141 +return value) plus a notice string (as second return value) are returned. 2.142 2.143 -This method is also available as :readuntil(...) for any other Lua file handle 2.144 -(including socket.input). 2.145 +If no data was available for reading, but no EOF was encountered, then an empty 2.146 +string is returned. 2.147 + 2.148 +In case of an I/O error, nil (as first return value) plus an error message (as 2.149 +second result value) are returned. 2.150 2.151 2.152 ### socket.remote_ip4 2.153 @@ -158,9 +183,43 @@ 2.154 Remote TCP port used for the connection. 2.155 2.156 2.157 +### socket:reset() 2.158 + 2.159 +Alias for socket:close(0). Closes the socket connection by sending a TCP RST 2.160 +packet if possible to indicate error condition. 2.161 + 2.162 +Returns true on success, or nil (as first result value) plus error message (as 2.163 +second result value) in case of an I/O error. Using this method on sockets that 2.164 +have already been closed (or reset) will throw an error. 2.165 + 2.166 +Warning: Previously sent (and flushed) data may be lost during transmission. 2.167 + 2.168 + 2.169 ### socket:write(...) 2.170 2.171 -Alias for socket.output:write(...) 2.172 +Takes a variable number of strings and sends them to the peer. The operation is 2.173 +buffered, so to actually send out the data, it is necessary to eventually call 2.174 +socket:flush(), socket:finish(), or socket:close(). 2.175 + 2.176 +In case of an I/O error, nil (as first return value) plus an error message (as 2.177 +second result value) are returned. On success, the socket userdata object is 2.178 +returned. 2.179 + 2.180 + 2.181 +### socket:write_nb(...) 2.182 + 2.183 +Takes a variable number of strings and sends them to the peer. The operation is 2.184 +buffered, so to actually send out the data, it is necessary to eventually call 2.185 +socket:flush_nb(), socket:flush(), socket:finish(), or socket:close(). 2.186 + 2.187 +This function always returns immediately (i.e. it does not block). If all data 2.188 +(but a small buffered portion) could be sent out, then zero is returned. 2.189 +Otherwise, all arguments that could not be sent are stored in a buffer of 2.190 +unlimited size (up to memory capabilities) and an integer is returned that 2.191 +indicates the number of bytes currently in the buffer. 2.192 + 2.193 +In case of an I/O error, nil (as first return value) plus an error message (as 2.194 +second result value) are returned. 2.195 2.196 2.197