1.1 --- a/reference.txt	Thu May 07 22:22:21 2015 +0200
     1.2 +++ b/reference.txt	Fri May 08 03:18:07 2015 +0200
     1.3 @@ -187,8 +187,9 @@
     1.4  
     1.5  ### socket:read_call(waitfunc, maxlen, terminator)
     1.6  
     1.7 -Same as socket:read(maxlen, terminator), but calls waitfunc(socket, "r") (in an
     1.8 -infinite loop) as long as the reading is blocked.
     1.9 +Same as socket:read(maxlen, terminator), but calls waitfunc(
    1.10 +moonbridge_io.block, socket, "r") (in an infinite loop) as long as the reading
    1.11 +is blocked.
    1.12  
    1.13  
    1.14  ### socket:read_nb(maxlen, terminator)
    1.15 @@ -255,8 +256,8 @@
    1.16  
    1.17  ### socket:write_call(waitfunc, ...)
    1.18  
    1.19 -Same as socket:write(...), but calls waitfunc(socket, "w") (in an infinite
    1.20 -loop) as long as the writing is blocked.
    1.21 +Same as socket:write(...), but calls waitfunc(moonbridge_io.block, socket,
    1.22 +"w") (in an infinite loop) as long as the writing is blocked.
    1.23  
    1.24  
    1.25  ### socket:write_nb(...)
    1.26 @@ -292,6 +293,18 @@
    1.27  listed below.
    1.28  
    1.29  
    1.30 +### moonbridge_io.block
    1.31 +
    1.32 +An opaque value (lightuserdata) used by yielding non-blocking I/O functions.
    1.33 +
    1.34 +When socket:read_yield(...) could not read from a socket, it yields the three
    1.35 +values moonbridge_io.block, the socket, and the string "r".
    1.36 +When socket:write_yield(...) could not write to a socket, it yields the three
    1.37 +values moonbridge_io.block, the socket, and the string "w".
    1.38 +
    1.39 +See reference for moonbridge_io.run(...) for further information.
    1.40 +
    1.41 +
    1.42  ### moonbridge_io.localconnect(path)
    1.43  
    1.44  Tries to connect to a local socket (also known as Unix Domain Socket). Returns
    1.45 @@ -339,6 +352,12 @@
    1.46  nil (as first return value) plus an error message (as second return value).
    1.47  
    1.48  
    1.49 +### moonbridge_io.multiblock
    1.50 +
    1.51 +An opaque value (lightuserdata) used by yielding non-blocking I/O functions.
    1.52 +See reference for moonbridge_io.run(...) for further information.
    1.53 +
    1.54 +
    1.55  ### moonbridge_io.poll(input_set, output_set, timeout)
    1.56  
    1.57  This function waits for at least one of the given file descriptors and/or
    1.58 @@ -352,6 +371,74 @@
    1.59  received.
    1.60  
    1.61  
    1.62 +### moonbridge_io.run(function_set, timeout_or_poll_func)
    1.63 +
    1.64 +Executes multiple coroutines (created via coroutine.wrap(...)) in the following
    1.65 +way:
    1.66 +
    1.67 +    function moonbridge_io.run(function_set, timeout_or_poll_func)
    1.68 +      local pairs = function(t) return next, t end  -- raw pairs
    1.69 +      local starttime = moonbridge_io.timeref()
    1.70 +      local read_fds, write_fds = {}, {}
    1.71 +      while true do
    1.72 +        local work_to_do = false
    1.73 +        for func, result_handler in pairs(function_set) do
    1.74 +          ::again::
    1.75 +          local r1, r2, r3, ... = func()
    1.76 +          if r1 == moonbridge_io.block then
    1.77 +            if type(r3) == "string" and string.match(r3, "r") then
    1.78 +              read_fds[r2] = true
    1.79 +            end
    1.80 +            if type(r3) == "string" and string.match(r3, "w") then
    1.81 +              write_fds[r2] = true
    1.82 +            end
    1.83 +            work_to_do = true
    1.84 +          elseif r1 == moonbridge_io.multiblock then
    1.85 +            for fd, active in pairs(r2) do
    1.86 +              if active then read_fds[fd] = true end
    1.87 +            end
    1.88 +            for fd, active in pairs(r3) do
    1.89 +              if active then write_fds[fd] = true end
    1.90 +            end
    1.91 +            work_to_do = true
    1.92 +          else
    1.93 +            if result_handler == true or result_handler(r1, r2, r3, ...) then
    1.94 +              function_set[func] = nil
    1.95 +            else
    1.96 +              goto again
    1.97 +            end
    1.98 +          end
    1.99 +        end
   1.100 +        if not work_to_do then
   1.101 +          return true  -- all tasks finished
   1.102 +        end
   1.103 +        if type(timeout_or_poll_func) == "function" then
   1.104 +          local poll_func = timeout_or_poll_func
   1.105 +          if
   1.106 +            poll_func(moonbridge_io.multiblock, read_fds, write_fds) == false
   1.107 +          then
   1.108 +            return false
   1.109 +          end
   1.110 +        elseif type(timeout_or_poll_func) == "number" then
   1.111 +          local timeout = timeout_or_poll_func
   1.112 +          if
   1.113 +            moonbridge_io.poll(
   1.114 +              read_fds,
   1.115 +              write_fds,
   1.116 +              timeout - moonbridge_io.timeref(start)
   1.117 +            ) == false
   1.118 +          then
   1.119 +            return false  -- timeout
   1.120 +          end
   1.121 +        else
   1.122 +          moonbridge_io.poll(read_fds, write_fds)
   1.123 +        end
   1.124 +        for fd in pairs(read_fds)  do read_fds[fd]  = nil end
   1.125 +        for fd in pairs(write_fds) do write_fds[fd] = nil end
   1.126 +      end
   1.127 +    end
   1.128 +
   1.129 +
   1.130  ### moonbridge_io.tcpconnect(hostname, port)
   1.131  
   1.132  Tries to open a TCP connection with the given host and TCP port number. Returns