# HG changeset patch # User jbe # Date 1428371428 -7200 # Node ID 6b26783f93239478b5c1184396576148769dc058 # Parent 54e6104c70a6310bd4aafe3240ca88501fda2864 write_nb returns total number of bytes buffered in case of block; Updated reference diff -r 54e6104c70a6 -r 6b26783f9323 moonbridge_io.c --- a/moonbridge_io.c Tue Apr 07 02:52:41 2015 +0200 +++ b/moonbridge_io.c Tue Apr 07 03:50:28 2015 +0200 @@ -268,13 +268,12 @@ handle->writebufcnt = 0; if (nonblocking) lua_pushinteger(L, 0); } else { - if (nonblocking) lua_pushinteger(L, handle->writeleft - handle->writebufcnt); + if (nonblocking) lua_pushinteger(L, handle->writeleft); } if (!nonblocking) lua_pushvalue(L, 1); return 1; moonbr_io_write_impl_block: - if (flush) lua_pushinteger(L, handle->writeleft); - else lua_pushinteger(L, handle->writeleft - handle->writebufcnt); + lua_pushinteger(L, handle->writeleft); return 1; } diff -r 54e6104c70a6 -r 6b26783f9323 reference.txt --- a/reference.txt Tue Apr 07 02:52:41 2015 +0200 +++ b/reference.txt Tue Apr 07 03:50:28 2015 +0200 @@ -52,42 +52,65 @@ a single socket object as argument, which is described below: -### socket:cancel() - -Closes the socket connection by sending a TCP RST package if possible to -indicate error condition. Returns true on success, or nil plus error message in -case of an I/O error. Using this method on sockets that have already been -closed (or canceled) will throw an error. - -Warning: Previously sent (and flushed) data may be lost during transmission. - - ### socket:close(timeout) Closes the socket connection (input and output stream) by flushing all data and -sending a TCP FIN package. Returns true on success, or nil plus error message -in case of an I/O error. Using this method on sockets that have already been -closed (or canceled) will throw an error. +sending a TCP FIN packet. If the timeout value is non-nil but zero, a TCP RST +is sent instead. If a positive timeout value is given and if the remote peer +doesn't respond with a TCP FIN within the given time, a TCP RST is sent in +addition to the previously sent TCP FIN packet. If the timeout value is nil or +negative, the call returns immediately and the operating system will wait for +the peer's TCP FIN packet. + +Returns true on success, or nil plus error message in case of an I/O error. +Using this method on sockets that have already been closed (or reset) will +throw an error. Warning: Pending data on the input stream may cause connection aborts (TCP RST) depending on the particular operating system used. All pending input data -should have been read before calling socket:close(). +should have been read (or drained) before calling socket:close(). + + +### socket:drain(maxlen, terminator) -The optional timeout parameter may be used to wait until all data has been sent -out, or until the timeout elapses (in which case a TCP RST is sent) whichever -happens first. A timeout value of 0 or nil causes immediate return and sending -of pending data in background (recommended). +Same as socket:read(maxlen, terminator), but discards the input and returns the +number of discarded bytes. If no bytes could be read but EOF was encountered, +then true is returned. + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. -### socket:flush() +### socket:drain_nb(maxlen, terminator) -Alias for socket.output:flush() +Same as socket:read_nb(maxlen, terminator), but discards the input and returns +the number of discarded bytes. If no bytes could be read but EOF was +encountered, then true is returned. + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. + -### socket.input +### socket:flush(...) + +Same as socket:write(...) but additionally flushes the socket (i.e. all pending +data is passed to the operating system). + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. On success, the socket userdata object is +returned. + -Lua file handle representing the input stream of the socket connection. -Supports the same methods as io.open()'s return values. +### socket:flush_nb(...) + +Same as socket:write_nb(...) but additionally flushes the socket (i.e. all +pending data is passed to the operating system). The total number of bytes that +could not be passed yet to the operating system is returned. Zero is returned +if all data could be flushed out. + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. ### socket.interval @@ -96,11 +119,6 @@ an elapsed interval timer. Otherwise nil. -### socket:lines() - -Alias for socket.input:lines() - - ### socket.local_ip4 Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a @@ -118,27 +136,34 @@ Local TCP port used for the connection. -### socket.output +### socket:read(maxlen, terminator) -Lua file handle representing the output stream of the socket connection. -Supports the same methods as io.open()'s return values. +Read up to maxlen bytes or until an optional termination character is +encountered (which is included in the result). The maxlen value may be nil, in +which case there is no limit on the number of bytes read. +If EOF is encountered before any data could be read, then false (as first +return value) plus a notice string (as second return value) are returned. -### socket:read(...) - -Alias for socket.input:read() +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. -### socket:readuntil(terminator, maxlen) +### socket:read_nb(maxlen, terminator) + +Read up to maxlen bytes, until an optional termination character is encountered +(which is included in the result), or until no more data is available for +reading. The maxlen value may be nil, in which case there is no limit on the +number of bytes read. -Reads as many bytes until a byte equal to the terminator value occurs. An -optional maximum length may be specified. The terminating byte is included in -the return value (unless the maximum length would be exceeded). On EOF, nil is -returned. In case of an I/O error, nil (as first result value) plus an error -message (as second result value) is returned. +If EOF is encountered before any data could be read, then false (as first +return value) plus a notice string (as second return value) are returned. -This method is also available as :readuntil(...) for any other Lua file handle -(including socket.input). +If no data was available for reading, but no EOF was encountered, then an empty +string is returned. + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. ### socket.remote_ip4 @@ -158,9 +183,43 @@ Remote TCP port used for the connection. +### socket:reset() + +Alias for socket:close(0). Closes the socket connection by sending a TCP RST +packet if possible to indicate error condition. + +Returns true on success, or nil (as first result value) plus error message (as +second result value) in case of an I/O error. Using this method on sockets that +have already been closed (or reset) will throw an error. + +Warning: Previously sent (and flushed) data may be lost during transmission. + + ### socket:write(...) -Alias for socket.output:write(...) +Takes a variable number of strings and sends them to the peer. The operation is +buffered, so to actually send out the data, it is necessary to eventually call +socket:flush(), socket:finish(), or socket:close(). + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned. On success, the socket userdata object is +returned. + + +### socket:write_nb(...) + +Takes a variable number of strings and sends them to the peer. The operation is +buffered, so to actually send out the data, it is necessary to eventually call +socket:flush_nb(), socket:flush(), socket:finish(), or socket:close(). + +This function always returns immediately (i.e. it does not block). If all data +(but a small buffered portion) could be sent out, then zero is returned. +Otherwise, all arguments that could not be sent are stored in a buffer of +unlimited size (up to memory capabilities) and an integer is returned that +indicates the number of bytes currently in the buffer. + +In case of an I/O error, nil (as first return value) plus an error message (as +second result value) are returned.