Correct documentation for issue #1523

net/* API documentation was not consistent with the implementation. The
`ev/*` module documentation was, however. On timeout, all networking
function calls raise an error and do not return nil. That was the old
behavior.

CHANGELOG.md

@@ -2,6 +2,8 @@
 All notable changes to this project will be documented in this file.
 
 ## ??? - Unreleased
+- Update timeout documentation for networking APIs: timeouts raise errors and do not return nil.
+- Add `janet_addtimeout_nil(double sec);` to the C API.
 - Change string hashing.
 - Fix string equality bug.
 - Add `assertf`

src/core/ev.c

@@ -625,6 +625,18 @@ void janet_addtimeout(double sec) {
     add_timeout(to);
 }
 
+/* Set timeout for the current root fiber but resume with nil instead of raising an error */
+void janet_addtimeout_nil(double sec) {
+    JanetFiber *fiber = janet_vm.root_fiber;
+    JanetTimeout to;
+    to.when = ts_delta(ts_now(), sec);
+    to.fiber = fiber;
+    to.curr_fiber = NULL;
+    to.sched_id = fiber->sched_id;
+    to.is_error = 0;
+    add_timeout(to);
+}
+
 void janet_ev_inc_refcount(void) {
     janet_atomic_inc(&janet_vm.listener_count);
 }

src/core/net.c

@@ -829,7 +829,7 @@ JANET_CORE_FN(cfun_stream_accept_loop,
 JANET_CORE_FN(cfun_stream_accept,
               "(net/accept stream &opt timeout)",
               "Get the next connection on a server stream. This would usually be called in a loop in a dedicated fiber. "
-              "Takes an optional timeout in seconds, after which will return nil. "
+              "Takes an optional timeout in seconds, after which will raise an error. "
               "Returns a new duplex stream which represents a connection to the client.") {
     janet_arity(argc, 1, 2);
     JanetStream *stream = janet_getabstract(argv, 0, &janet_stream_type);
@@ -864,7 +864,7 @@ JANET_CORE_FN(cfun_stream_read,
 JANET_CORE_FN(cfun_stream_chunk,
               "(net/chunk stream nbytes &opt buf timeout)",
               "Same a net/read, but will wait for all n bytes to arrive rather than return early. "
-              "Takes an optional timeout in seconds, after which will return nil.") {
+              "Takes an optional timeout in seconds, after which will raise an error.") {
     janet_arity(argc, 2, 4);
     JanetStream *stream = janet_getabstract(argv, 0, &janet_stream_type);
     janet_stream_flags(stream, JANET_STREAM_READABLE | JANET_STREAM_SOCKET);
@@ -878,7 +878,7 @@ JANET_CORE_FN(cfun_stream_chunk,
 JANET_CORE_FN(cfun_stream_recv_from,
               "(net/recv-from stream nbytes buf &opt timeout)",
               "Receives data from a server stream and puts it into a buffer. Returns the socket-address the "
-              "packet came from. Takes an optional timeout in seconds, after which will return nil.") {
+              "packet came from. Takes an optional timeout in seconds, after which will raise an error.") {
     janet_arity(argc, 3, 4);
     JanetStream *stream = janet_getabstract(argv, 0, &janet_stream_type);
     janet_stream_flags(stream, JANET_STREAM_UDPSERVER | JANET_STREAM_SOCKET);
@@ -892,7 +892,7 @@ JANET_CORE_FN(cfun_stream_recv_from,
 JANET_CORE_FN(cfun_stream_write,
               "(net/write stream data &opt timeout)",
               "Write data to a stream, suspending the current fiber until the write "
-              "completes. Takes an optional timeout in seconds, after which will return nil. "
+              "completes. Takes an optional timeout in seconds, after which will raise an error. "
               "Returns nil, or raises an error if the write failed.") {
     janet_arity(argc, 2, 3);
     JanetStream *stream = janet_getabstract(argv, 0, &janet_stream_type);
@@ -911,7 +911,7 @@ JANET_CORE_FN(cfun_stream_write,
 JANET_CORE_FN(cfun_stream_send_to,
               "(net/send-to stream dest data &opt timeout)",
               "Writes a datagram to a server stream. dest is a the destination address of the packet. "
-              "Takes an optional timeout in seconds, after which will return nil. "
+              "Takes an optional timeout in seconds, after which will raise an error. "
               "Returns stream.") {
     janet_arity(argc, 3, 4);
     JanetStream *stream = janet_getabstract(argv, 0, &janet_stream_type);

src/include/janet.h

@@ -1442,6 +1442,7 @@ JANET_NO_RETURN JANET_API void janet_sleep_await(double sec);
 /* For use inside listeners - adds a timeout to the current fiber, such that
  * it will be resumed after sec seconds if no other event schedules the current fiber. */
 JANET_API void janet_addtimeout(double sec);
+JANET_API void janet_addtimeout_nil(double sec);
 JANET_API void janet_ev_inc_refcount(void);
 JANET_API void janet_ev_dec_refcount(void);