# HG changeset patch
# User jbe
# Date 1428175710 -7200
# Node ID 4628be0a7b98a2a69ea5f478075969e02c0c234e
# Parent  360a1860bb14c04c63d5f90b75615d825593f0d1
Updated reference to include xread, xread_nb, write_nb

diff -r 360a1860bb14 -r 4628be0a7b98 reference.txt
--- a/reference.txt	Sat Apr 04 21:11:15 2015 +0200
+++ b/reference.txt	Sat Apr 04 21:28:30 2015 +0200
@@ -110,36 +110,32 @@
 Supports the same methods as io.open()'s return values.
 
 
-### socket.input:pending()
-
-Returns true if there is at least one byte to read. In case of I/O errors, true
-is returned as well (to avoid lockup and cause error on subsequent read).
+### socket.input:xread(maxlen, terminator)
 
-Note: Subsequent calls of socket.input:read(...) or socket.input:readuntil(...)
-may still block when attempting to read more than one byte. To avoid hanging
-processes, the timeout(...) function may be used as a watchdog that will
-terminate the process in case of unexpected delay. Because file handles are
-buffered, data may be still pending even if the underlaying file descriptor
-does not have any more data to read. Thus, all file handles passed to
-io.poll(...) to wait for reading should be tested for pending data first.
+Reads as many bytes until either the maximum length is reached (first argument)
+or a terminating character (second argument as string with a length of 1) is
+encountered. In the latter case, the terminating character will be included in
+the result.
 
-This method is also available as :pending() for any other Lua file handle.
+On EOF, false (as first result value) and an error message (as second result
+value) are returned. In case of an I/O error, nil and an error message are
+returned.
+
+This method is also available for any other Lua file handle.
 
 
-### socket.input:readuntil(terminator, maxlen)
+### socket.input:xread_nb(maxlen, terminator)
 
-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.
+Same as socket.input:xread(maxlen, terminator), but non-blocking. If no more
+data can be read due to blocking, this method returns a string containing the
+data which has already been read. If no data could be read due to blocking,
+then an empty string is returned.
 
-Note: This function may provide a significant speedup compared to byte-wise
-reading using socket.input:read(1) in a loop. However, this function will block
-when no data is available. The timeout(...) function may be used as a watchdog
-that will terminate the process in case of unexpected delay.
+On EOF, false (as first result value) and an error message (as second result
+value) are returned. In case of an I/O error, nil and an error message are
+returned.
 
-This method is also available as :readuntil(...) for any other Lua file handle.
+This method is also available for any other Lua file handle.
 
 
 ### socket.interval
@@ -187,16 +183,24 @@
 transmitted data.
 
 
+### socket.output:write_nb(...)
+
+Non-blocking write. This function attempts to write as many bytes as possible,
+returning a string containing all data that could not be written due to
+blocking (potentially concatenating some or all remaining arguments to create
+that string).
+
+In case of an I/O error, nil (as first result value) and an error message (as
+second result value) are returned.
+
+This method is also available for any other Lua file handle.
+
+
 ### socket:read(...)
 
 Alias for socket.input:read()
 
 
-### socket:readuntil(terminator, maxlen)
-
-Alias for socket.input:readuntil(terminator, maxlen)
-
-
 ### socket.remote_ip4
 
 Remote IPv4 address used for the connection. Encoded as 4 raw bytes in form of
@@ -219,6 +223,21 @@
 Alias for socket.output:write(...)
 
 
+### socket:write_nb(...)
+
+Alias for socket.output:write(...)
+
+
+### socket:xread(maxlen, terminator)
+
+Alias for socket.input:xread(...)
+
+
+### socket:xread_nb(maxlen, terminator)
+
+Alias for socket.input:xread_nb(...)
+
+
 
 HTTP module
 -----------