/*
    * Copyright (C) 2022 Jo-Philipp Wich <jo@mein.io>
    *
    * Permission to use, copy, modify, and/or distribute this software for any
    * purpose with or without fee is hereby granted, provided that the above
    * copyright notice and this permission notice appear in all copies.
    *
    * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
   * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
   * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
   * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
   */
  
  /**
   * # OpenWrt uloop event loop
   *
   * The `uloop` binding provides functions for integrating with the OpenWrt
   * {@link https://github.com/openwrt/libubox/blob/master/uloop.h uloop library}.
   *
   * Functions can be individually imported and directly accessed using the
   * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#named_import named import}
   * syntax:
   *
   *   ```javascript
   *   import { init, handle, timer, interval, process, signal, task, run } from 'uloop';
   *
   *   init();
   *
   *   handle(…);
   *   timer(…);
   *   interval(…);
   *   process(…);
   *   signal(…);
   *   task(…);
   *
   *   run();
   *   ```
   *
   * Alternatively, the module namespace can be imported using a wildcard import
   * statement:
   *
   *   ```javascript
   *   import * as uloop from 'uloop';
   *
   *   uloop.init();
   *
   *   uloop.handle(…);
   *   uloop.timer(…);
   *   uloop.interval(…);
   *   uloop.process(…);
   *   uloop.signal(…);
   *   uloop.task(…);
   *
   *   uloop.run();
   *   ```
   *
   * Additionally, the uloop binding namespace may also be imported by invoking
   * the `ucode` interpreter with the `-luloop` switch.
   *
   * @module uloop
   */
  
  #include <errno.h>
  #include <string.h>
  #include <unistd.h>
  #include <limits.h>
  #include <fcntl.h>
  
  #include <libubox/uloop.h>
  
  #include "ucode/module.h"
  #include "ucode/platform.h"
  
  #define ok_return(expr) do { last_error = 0; return (expr); } while(0)
  #define err_return(err) do { last_error = err; return NULL; } while(0)
  
  static int last_error = 0;
  
  typedef struct {
          uc_vm_t *vm;
          uc_value_t *obj;
  } uc_uloop_cb_t;
  
  static void *
  uc_uloop_alloc(uc_vm_t *vm, const char *type, size_t size, uc_value_t *func)
  {
          uc_uloop_cb_t *cb;
          uc_value_t *obj;
  
          obj = ucv_resource_create_ex(vm, type, (void **)&cb, 2, size);
          if (!obj)
                  return NULL;
  
          cb->vm = vm;
          cb->obj = ucv_get(obj);
          ucv_resource_persistent_set(obj, true);
         ucv_resource_value_set(obj, 0, ucv_get(func));
 
         return cb;
 }
 
 static void
 uc_uloop_cb_free(uc_uloop_cb_t *cb)
 {
         uc_value_t *obj = cb->obj;
 
         if (!obj)
                 return;
 
         cb->obj = NULL;
 
         ucv_resource_persistent_set(obj, false);
         ucv_put(obj);
 }
 
 static bool
 uc_uloop_vm_call(uc_vm_t *vm, bool mcall, size_t nargs)
 {
         uc_value_t *exh, *val;
 
         if (uc_vm_call(vm, mcall, nargs) == EXCEPTION_NONE)
                 return true;
 
         exh = uc_vm_registry_get(vm, "uloop.ex_handler");
         if (!ucv_is_callable(exh))
                 goto error;
 
         val = uc_vm_exception_object(vm);
         uc_vm_stack_push(vm, ucv_get(exh));
         uc_vm_stack_push(vm, val);
 
         if (uc_vm_call(vm, false, 1) != EXCEPTION_NONE)
                 goto error;
 
         ucv_put(uc_vm_stack_pop(vm));
 
         return false;
 
 error:
         uloop_end();
         return false;
 }
 
 static void
 uc_uloop_cb_invoke(uc_uloop_cb_t *cb, uc_value_t *arg)
 {
         uc_vm_t *vm = cb->vm;
         uc_value_t *func = ucv_resource_value_get(cb->obj, 0);
 
         if (!ucv_is_callable(func))
                 return;
 
         uc_vm_stack_push(vm, ucv_get(cb->obj));
         uc_vm_stack_push(vm, ucv_get(func));
         uc_vm_stack_push(vm, ucv_get(arg));
 
         if (uc_uloop_vm_call(vm, true, 1))
                 ucv_put(uc_vm_stack_pop(vm));
 }
 
 /**
  * Retrieves the last error message.
  *
  * This function retrieves the last error message generated by the uloop event loop.
  * If no error occurred, it returns `null`.
  *
  * @function module:uloop#error
  *
  * @returns {?string}
  * Returns the last error message as a string, or `null` if no error occurred.
  *
  * @example
  * // Retrieve the last error message
  * const errorMessage = uloop.error();
  *
  * if (errorMessage)
  *     printf(`Error message: ${errorMessage}\n`);
  * else
  *     printf("No error occurred\n");
  */
 static uc_value_t *
 uc_uloop_error(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *errmsg;
 
         if (last_error == 0)
                 return NULL;
 
         errmsg = ucv_string_new(strerror(last_error));
         last_error = 0;
 
         return errmsg;
 }
 
 /**
  * Initializes the uloop event loop.
  *
  * This function initializes the uloop event loop, allowing subsequent
  * usage of uloop functionalities. It takes no arguments.
  *
  * Returns `true` on success.
  * Returns `null` if an error occurred during initialization.
  *
  * @function module:uloop#init
  *
  * @returns {?boolean}
  * Returns `true` on success, `null` on error.
  *
  * @example
  * // Initialize the uloop event loop
  * const success = uloop.init();
  *
  * if (success)
  *     printf("uloop event loop initialized successfully\n");
  * else
  *     die(`Initialization failure: ${uloop.error()}\n`);
  */
 static uc_value_t *
 uc_uloop_init(uc_vm_t *vm, size_t nargs)
 {
         int rv = uloop_init();
 
         if (rv == -1)
                 err_return(errno);
 
         ok_return(ucv_boolean_new(true));
 }
 
 /**
  * Runs the uloop event loop.
  *
  * This function starts running the uloop event loop, allowing it to handle
  * scheduled events and callbacks. If a timeout value is provided and is
  * non-negative, the event loop will run for that amount of milliseconds
  * before returning. If the timeout is omitted or negative, the event loop
  * runs indefinitely until explicitly stopped.
  *
  * @function module:uloop#run
  *
  * @param {number} [timeout=-1]
  * Optional. The timeout value in milliseconds for running the event loop.
  * Defaults to -1, indicating an indefinite run.
  *
  * @returns {?boolean}
  * Returns `true` on success, `null` on error.
  *
  * @example
  * // Run the uloop event loop indefinitely
  * const success = uloop.run();
  * if (success)
  *     printf("uloop event loop ran successfully\n");
  * else
  *     die(`Error occurred during uloop execution: ${uloop.error()}\n`);
  *
  * // Run the uloop event loop for 1000 milliseconds
  * const success = uloop.run(1000);
  * if (success)
  *     printf("uloop event loop ran successfully\n");
  * else
  *     die(`Error occurred during uloop execution: ${uloop.error()}\n`);
  */
 static uc_value_t *
 uc_uloop_run(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *timeout = uc_fn_arg(0);
         int t, rv;
 
         errno = 0;
         t = timeout ? (int)ucv_int64_get(timeout) : -1;
 
         if (errno)
                 err_return(errno);
 
         rv = uloop_run_timeout(t);
 
         ok_return(ucv_int64_new(rv));
 }
 
 /**
  * Checks if the uloop event loop is currently shutting down.
  *
  * This function checks whether the uloop event loop is currently in the process
  * of shutting down.
  *
  * @function module:uloop#cancelling
  *
  * @returns {boolean}
  * Returns `true` if uloop is currently shutting down, `false` otherwise.
  *
  * @example
  * // Check if the uloop event loop is shutting down
  * const shuttingDown = uloop.cancelling();
  * if (shuttingDown)
  *     printf("uloop event loop is currently shutting down\n");
  * else
  *     printf("uloop event loop is not shutting down\n");
  */
 static uc_value_t *
 uc_uloop_cancelling(uc_vm_t *vm, size_t nargs)
 {
         ok_return(ucv_boolean_new(uloop_cancelling()));
 }
 
 /**
  * Checks if the uloop event loop is currently running.
  *
  * This function checks whether the uloop event loop is currently started
  * and running.
  *
  * @function module:uloop#running
  *
  * @returns {boolean}
  * Returns `true` if the event loop is currently running, `false` otherwise.
  *
  * @example
  * // Check if the uloop event loop is running
  * const isRunning = uloop.running();
  * if (isRunning)
  *     printf("uloop event loop is currently running\n");
  * else
  *     printf("uloop event loop is not running\n");
  */
 static uc_value_t *
 uc_uloop_running(uc_vm_t *vm, size_t nargs)
 {
         bool prev = uloop_cancelled;
         bool active;
 
         uloop_cancelled = true;
         active = uloop_cancelling();
         uloop_cancelled = prev;
 
         ok_return(ucv_boolean_new(active));
 }
 
 /**
  * Halts the uloop event loop.
  *
  * This function halts the uloop event loop, stopping its execution and
  * preventing further processing of scheduled events and callbacks.
  *
  * Expired timeouts and already queued event callbacks are still run to
  * completion.
  *
  * @function module:uloop#end
  *
  * @returns {void}
  * This function does not return any value.
  *
  * @example
  * // Halt the uloop event loop
  * uloop.end();
  */
 static uc_value_t *
 uc_uloop_end(uc_vm_t *vm, size_t nargs)
 {
         uloop_end();
 
         ok_return(NULL);
 }
 
 /**
  * Stops the uloop event loop and cancels pending timeouts and events.
  *
  * This function immediately stops the uloop event loop, cancels all pending
  * timeouts and events, unregisters all handles, and deallocates associated
  * resources.
  *
  * @function module:uloop#done
  *
  * @returns {void}
  * This function does not return any value.
  *
  * @example
  * // Stop the uloop event loop and clean up resources
  * uloop.done();
  */
 static uc_value_t *
 uc_uloop_done(uc_vm_t *vm, size_t nargs)
 {
         uloop_done();
 
         ok_return(NULL);
 }
 
 
 /**
  * Represents a uloop timer instance as returned by
  * {@link module:uloop#timer|timer()}.
  *
  * @class module:uloop.timer
  * @hideconstructor
  *
  * @see {@link module:uloop#timer|timer()}
  *
  * @example
  *
  * const timeout = uloop.timer(…);
  *
  * timeout.set(…);
  * timeout.remaining();
  * timeout.cancel();
  */
 typedef struct {
         uc_uloop_cb_t cb;
         struct uloop_timeout timeout;
 } uc_uloop_timer_t;
 
 static int
 uc_uloop_timeout_clear(uc_uloop_timer_t *timer)
 {
         int rv = uloop_timeout_cancel(&timer->timeout);
 
         uc_uloop_cb_free(&timer->cb);
 
         return rv;
 }
 
 /**
  * Rearms the uloop timer with the specified timeout.
  *
  * This method rearms the uloop timer with the specified timeout value,
  * allowing it to trigger after the specified amount of time. If no timeout
  * value is provided or if the provided value is negative, the timer remains
  * disabled until rearmed with a positive timeout value.
  *
  * @function module:uloop.timer#set
  *
  * @param {number} [timeout=-1]
  * Optional. The timeout value in milliseconds until the timer expires.
  * Defaults to -1, which disables the timer until rearmed with a positive timeout.
  *
  * @returns {?boolean}
  * Returns `true` on success, `null` on error, such as an invalid timeout argument.
  *
  * @example
  * const timeout = uloop.timer(…);
  *
  * // Rearm the uloop timer with a timeout of 1000 milliseconds
  * timeout.set(1000);
  *
  * // Disable the uloop timer
  * timeout.set();
  */
 static uc_value_t *
 uc_uloop_timer_set(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_timer_t *timer = uc_fn_thisval("uloop.timer");
         uc_value_t *timeout = uc_fn_arg(0);
         int t, rv;
 
         if (!timer)
                 err_return(EINVAL);
 
         errno = 0;
         t = timeout ? (int)ucv_int64_get(timeout) : -1;
 
         if (errno)
                 err_return(errno);
 
         rv = uloop_timeout_set(&timer->timeout, t);
 
         ok_return(ucv_boolean_new(rv == 0));
 }
 
 /**
  * Returns the number of milliseconds until the uloop timer expires.
  *
  * This method returns the remaining time until the uloop timer expires. If
  * the timer is not armed (i.e., disabled), it returns -1.
  *
  * @function module:uloop.timer#remaining
  *
  * @returns {number}
  * The number of milliseconds until the timer expires, or -1 if the timer is not armed.
  *
  * @example
  * // Get the remaining time until the uloop timer expires (~500ms)
  * const remainingTime = timer.remaining();
  * if (remainingTime !== -1)
  *     printf("Time remaining until timer expires: %d ms\n", remainingTime);
  * else
  *     printf("Timer is not armed\n");
  */
 static uc_value_t *
 uc_uloop_timer_remaining(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_timer_t *timer = uc_fn_thisval("uloop.timer");
         int64_t rem;
 
         if (!timer)
                 err_return(EINVAL);
 
 #ifdef HAVE_ULOOP_TIMEOUT_REMAINING64
         rem = uloop_timeout_remaining64(&timer->timeout);
 #else
         rem = (int64_t)uloop_timeout_remaining(&timer->timeout);
 #endif
 
         ok_return(ucv_int64_new(rem));
 }
 
 /**
  * Cancels the uloop timer, disarming it and removing it from the event loop.
  *
  * This method destroys the uloop timer and releases its associated resources.
  *
  * @function module:uloop.timer#cancel
  *
  * @returns {boolean}
  * Returns `true` on success.
  *
  * @example
  * // Cancel the uloop timer
  * timer.cancel();
  */
 static uc_value_t *
 uc_uloop_timer_cancel(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_timer_t *timer = uc_fn_thisval("uloop.timer");
         int rv;
 
         if (!timer)
                 err_return(EINVAL);
 
         rv = uc_uloop_timeout_clear(timer);
 
         ok_return(ucv_boolean_new(rv == 0));
 }
 
 static void
 uc_uloop_timer_cb(struct uloop_timeout *timeout)
 {
         uc_uloop_timer_t *timer = container_of(timeout, uc_uloop_timer_t, timeout);
 
         uc_uloop_cb_invoke(&timer->cb, NULL);
 }
 
 /**
  * Creates a timer instance for scheduling callbacks.
  *
  * This function creates a timer instance for scheduling callbacks to be
  * executed after a specified timeout duration. It takes an optional timeout
  * parameter, which defaults to -1, indicating that the timer is initially not
  * armed and can be enabled later by invoking the `.set(timeout)` method on the
  * instance.
  *
  * A callback function must be provided to be executed when the timer expires.
  *
  * @function module:uloop#timer
  *
  * @param {number} [timeout=-1]
  * Optional. The timeout duration in milliseconds. Defaults to -1, indicating
  * the timer is not initially armed.
  *
  * @param {Function} callback
  * The callback function to be executed when the timer expires.
  *
  * @returns {?module:uloop.timer}
  * Returns a timer instance for scheduling callbacks.
  * Returns `null` when the timeout or callback arguments are invalid.
  *
  * @example
  * // Create a timer with a callback to be executed after 1000 milliseconds
  * const myTimer = uloop.timer(1000, () => {
  *     printf("Timer expired!\n");
  * });
  *
  * // Later enable the timer with a timeout of 500 milliseconds
  * myTimer.set(500);
  */
 static uc_value_t *
 uc_uloop_timer(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *timeout = uc_fn_arg(0);
         uc_value_t *callback = uc_fn_arg(1);
         uc_uloop_timer_t *timer;
         int t;
 
         errno = 0;
         t = timeout ? ucv_int64_get(timeout) : -1;
 
         if (errno)
                 err_return(errno);
 
         if (!ucv_is_callable(callback))
                 err_return(EINVAL);
 
         timer = uc_uloop_alloc(vm, "uloop.timer", sizeof(*timer), callback);
         timer->timeout.cb = uc_uloop_timer_cb;
 
         if (t >= 0)
                 uloop_timeout_set(&timer->timeout, t);
 
         ok_return(timer->cb.obj);
 }
 
 
 /**
  * Represents a uloop handle instance as returned by
  * {@link module:uloop#handle|handle()}.
  *
  * @class module:uloop.handle
  * @hideconstructor
  *
  * @see {@link module:uloop#handle|handle()}
  *
  * @example
  *
  * const handle = uloop.handle(…);
  *
  * handle.fileno();
  * handle.handle();
  *
  * handle.delete();
  */
 typedef struct {
         uc_uloop_cb_t cb;
         struct uloop_fd fd;
 } uc_uloop_handle_t;
 
 static int
 uc_uloop_handle_clear(uc_uloop_handle_t *handle)
 {
         int rv = uloop_fd_delete(&handle->fd);
 
         uc_uloop_cb_free(&handle->cb);
 
         return rv;
 }
 
 /**
  * Returns the file descriptor number.
  *
  * This method returns the file descriptor number associated with the underlying
  * handle, which might refer to a socket or file instance.
  *
  * @function module:uloop.handle#fileno
  *
  * @returns {number}
  * The file descriptor number associated with the handle.
  *
  * @example
  * // Get the file descriptor number associated with the uloop handle
  * const fd = handle.fileno();
  * printf("File descriptor number: %d\n", fd);
  */
 static uc_value_t *
 uc_uloop_handle_fileno(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_handle_t *handle = uc_fn_thisval("uloop.handle");
 
         if (!handle)
                 err_return(EINVAL);
 
         ok_return(ucv_int64_new(handle->fd.fd));
 }
 
 /**
  * Returns the underlying file or socket instance.
  *
  * This method returns the underlying file or socket instance associated with
  * the uloop handle.
  *
  * @function module:uloop.handle#handle
  *
  * @returns {module:fs.file|module:fs.proc|module:socket.socket}
  * The underlying file or socket instance associated with the handle.
  *
  * @example
  * // Get the associated file or socket instance
  * const fileOrSocket = handle.handle();
  * printf("Handle: %s\n", fileOrSocket); // e.g. <socket 0x5> or <fs.proc …>
  */
 static uc_value_t *
 uc_uloop_handle_handle(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_handle_t *handle = uc_fn_thisval("uloop.handle");
 
         if (!handle)
                 err_return(EINVAL);
 
         ok_return(ucv_get(ucv_resource_value_get(handle->cb.obj, 1)));
 }
 
 /**
  * Unregisters the uloop handle.
  *
  * This method unregisters the uloop handle from the uloop event loop and frees
  * any associated resources. After calling this method, the handle instance
  * should no longer be used.
  *
  * @function module:uloop.handle#delete
  *
  * @returns {void}
  * This function does not return a value.
  *
  * @example
  * // Unregister the uloop handle and free associated resources
  * handle.delete();
  * printf("Handle deleted successfully\n");
  */
 static uc_value_t *
 uc_uloop_handle_delete(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_handle_t *handle = uc_fn_thisval("uloop.handle");
         int rv;
 
         if (!handle)
                 err_return(EINVAL);
 
         rv = uc_uloop_handle_clear(handle);
 
         if (rv != 0)
                 err_return(errno);
 
         ok_return(ucv_boolean_new(true));
 }
 
 static void
 uc_uloop_handle_cb(struct uloop_fd *fd, unsigned int flags)
 {
         uc_uloop_handle_t *handle = container_of(fd, uc_uloop_handle_t, fd);
         uc_value_t *f = ucv_uint64_new(flags);
 
         uc_uloop_cb_invoke(&handle->cb, f);
         ucv_put(f);
 }
 
 static int
 get_fd(uc_vm_t *vm, uc_value_t *val)
 {
         uc_value_t *fn;
         int64_t n;
         int fd;
 
         fn = ucv_property_get(val, "fileno");
 
         if (ucv_is_callable(fn)) {
                 uc_vm_stack_push(vm, ucv_get(val));
                 uc_vm_stack_push(vm, ucv_get(fn));
 
                 if (uc_vm_call(vm, true, 0) == EXCEPTION_NONE)  {
                         val = uc_vm_stack_pop(vm);
                 }
                 else {
                         errno = EBADF;
                         val = NULL;
                 }
         }
         else {
                 ucv_get(val);
         }
 
         n = ucv_int64_get(val);
 
         if (errno) {
                 fd = -1;
         }
         else if (n < 0 || n > (int64_t)INT_MAX) {
                 errno = EBADF;
                 fd = -1;
         }
         else {
                 fd = (int)n;
         }
 
         ucv_put(val);
 
         return fd;
 }
 
 /**
  * Creates a handle instance for monitoring file descriptor events.
  *
  * This function creates a handle instance for monitoring events on a file
  * descriptor, file, or socket. It takes the file or socket handle, a callback
  * function to be invoked when the specified IO events occur, and bitwise OR-ed
  * flags of IO events (`ULOOP_READ`, `ULOOP_WRITE`) that the callback should be
  * invoked for.
  *
  * @function module:uloop#handle
  *
  * @param {number|module:fs.file|module:fs.proc|module:socket.socket} handle
  * The file handle (descriptor number, file or socket instance).
  *
  * @param {Function} callback
  * The callback function to be invoked when the specified IO events occur.
  *
  * @param {number} events
  * Bitwise OR-ed flags of IO events (`ULOOP_READ`, `ULOOP_WRITE`) that the
  * callback should be invoked for.
  *
  * @returns {?module:uloop.handle}
  * Returns a handle instance for monitoring file descriptor events.
  * Returns `null` when the handle, callback or signal arguments are invalid.
  *
  * @example
  * // Create a handle for monitoring read events on file descriptor 3
  * const myHandle = uloop.handle(3, (events) => {
  *     if (events & ULOOP_READ)
  *         printf("Read event occurred!\n");
  * }, uloop.ULOOP_READ);
  *
  * // Check socket for writability
  * const sock = socket.connect("example.org", 80);
  * uloop.handle(sock, (events) => {
  *     sock.send("GET / HTTP/1.0\r\n\r\n");
  * }, uloop.ULOOP_WRITE)
  */
 static uc_value_t *
 uc_uloop_handle(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *fileno = uc_fn_arg(0);
         uc_value_t *callback = uc_fn_arg(1);
         uc_value_t *flags = uc_fn_arg(2);
         uc_uloop_handle_t *handle;
         int fd, ret;
         uint64_t f;
 
         fd = get_fd(vm, fileno);
 
         if (fd == -1)
                 err_return(errno);
 
         f = ucv_uint64_get(flags);
 
         if (errno)
                 err_return(errno);
 
         if (f == 0 || f > (uint64_t)UINT_MAX)
                 err_return(EINVAL);
 
         if (!ucv_is_callable(callback))
                 err_return(EINVAL);
 
         handle = uc_uloop_alloc(vm, "uloop.handle", sizeof(*handle), callback);
         handle->fd.fd = fd;
         handle->fd.cb = uc_uloop_handle_cb;
 
         ret = uloop_fd_add(&handle->fd, (unsigned int)f);
         if (ret != 0) {
                 ucv_put(handle->cb.obj);
                 err_return(errno);
         }
 
         ucv_resource_value_set(handle->cb.obj, 1, ucv_get(fileno));
         ok_return(handle->cb.obj);
 }
 
 
 /**
  * Represents a uloop process instance as returned by
  * {@link module:uloop#process|process()}.
  *
  * @class module:uloop.process
  * @hideconstructor
  *
  * @see {@link module:uloop#process|process()}
  *
  * @example
  *
  * const proc = uloop.process(…);
  *
  * proc.pid();
  *
  * proc.delete();
  */
 typedef struct {
         uc_uloop_cb_t cb;
         struct uloop_process process;
 } uc_uloop_process_t;
 
 static int
 uc_uloop_process_clear(uc_uloop_process_t *process)
 {
         int rv = uloop_process_delete(&process->process);
 
         uc_uloop_cb_free(&process->cb);
 
         return rv;
 }
 
 /**
  * Returns the process ID.
  *
  * This method returns the process ID (PID) of the operating system process
  * launched by {@link module:uloop#process|process().
  *
  * @function module:uloop.process#pid
  *
  * @returns {number}
  * The process ID (PID) of the associated launched process.
  *
  * @example
  * const proc = uloop.process(…);
  *
  * printf("Process ID: %d\n", proc.pid());
  */
 static uc_value_t *
 uc_uloop_process_pid(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_process_t *process = uc_fn_thisval("uloop.process");
 
         if (!process)
                 err_return(EINVAL);
 
         ok_return(ucv_int64_new(process->process.pid));
 }
 
 /**
  * Unregisters the process from uloop.
  *
  * This method unregisters the process from the uloop event loop and releases
  * any associated resources. However, note that the operating system process
  * itself is not terminated by this method.
  *
  * @function module:uloop.process#delete
  *
  * @returns {boolean}
  * Returns `true` on success.
  *
  * @example
  * const proc = uloop.process(…);
  *
  * proc.delete();
  */
 static uc_value_t *
 uc_uloop_process_delete(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_process_t *process = uc_fn_thisval("uloop.process");
         int rv;
 
         if (!process)
                 err_return(EINVAL);
 
         rv = uc_uloop_process_clear(process);
 
         if (rv != 0)
                 err_return(EINVAL);
 
         ok_return(ucv_boolean_new(true));
 }
 
 static void
 uc_uloop_process_cb(struct uloop_process *proc, int exitcode)
 {
         uc_uloop_process_t *process = container_of(proc, uc_uloop_process_t, process);
         uc_value_t *e = ucv_int64_new(exitcode >> 8);
 
         uc_uloop_cb_invoke(&process->cb, e);
         uc_uloop_process_clear(process);
         ucv_put(e);
 }
 
 /**
  * Creates a process instance for executing external programs.
  *
  * This function creates a process instance for executing external programs.
  * It takes the executable path string, an optional string array as the argument
  * vector, an optional dictionary describing environment variables, and a
  * callback function to be invoked when the invoked process ends.
  *
  * @function module:uloop#process
  *
  * @param {string} executable
  * The path to the executable program.
  *
  * @param {string[]} [args]
  * Optional. An array of strings representing the arguments passed to the
  * executable.
  *
  * @param {Object<string, *>} [env]
  * Optional. A dictionary describing environment variables for the process.
  *
  * @param {Function} callback
  * The callback function to be invoked when the invoked process ends.
  *
  * @returns {?module:uloop.process}
  * Returns a process instance for executing external programs.
  * Returns `null` on error, e.g. due to `exec()` failure or invalid arguments.
  *
  * @example
  * // Create a process instance for executing 'ls' command
  * const myProcess = uloop.process("/bin/ls", ["-l", "/tmp"], null, (code) => {
  *     printf(`Process exited with code ${code}\n`);
  * });
  */
 static uc_value_t *
 uc_uloop_process(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *executable = uc_fn_arg(0);
         uc_value_t *arguments = uc_fn_arg(1);
         uc_value_t *env_arg = uc_fn_arg(2);
         uc_value_t *callback = uc_fn_arg(3);
         uc_uloop_process_t *process;
         uc_stringbuf_t *buf;
         char **argp, **envp;
         pid_t pid;
         size_t i;
 
         if (ucv_type(executable) != UC_STRING ||
             (arguments && ucv_type(arguments) != UC_ARRAY) ||
             (env_arg && ucv_type(env_arg) != UC_OBJECT) ||
             !ucv_is_callable(callback)) {
                 err_return(EINVAL);
         }
 
         pid = fork();
 
         if (pid == -1)
                 err_return(errno);
 
         if (pid == 0) {
                 argp = calloc(ucv_array_length(arguments) + 2, sizeof(char *));
                 envp = calloc(ucv_object_length(env_arg) + 1, sizeof(char *));
 
                 if (!argp || !envp)
                         _exit(-1);
 
                 argp[0] = ucv_to_string(vm, executable);
 
                 for (i = 0; i < ucv_array_length(arguments); i++)
                         argp[i+1] = ucv_to_string(vm, ucv_array_get(arguments, i));
 
                 i = 0;
 
                 ucv_object_foreach(env_arg, envk, envv) {
                         buf = xprintbuf_new();
 
                         ucv_stringbuf_printf(buf, "%s=", envk);
                         ucv_to_stringbuf(vm, buf, envv, false);
 
                         envp[i++] = buf->buf;
 
                         free(buf);
                 }
 
                 execvpe((const char *)ucv_string_get(executable),
                         (char * const *)argp, (char * const *)envp);
 
                 _exit(-1);
         }
 
         process = uc_uloop_alloc(vm, "uloop.process", sizeof(*process), callback);
         process->process.pid = pid;
         process->process.cb = uc_uloop_process_cb;
         uloop_process_add(&process->process);
 
         ok_return(process->cb.obj);
 }
 
 
 static bool
 readall(int fd, void *buf, size_t len)
 {
         ssize_t rlen;
 
         while (len > 0) {
                 rlen = read(fd, buf, len);
 
                 if (rlen == -1) {
                         if (errno == EINTR)
                                 continue;
 
                         return false;
                 }
 
                 if (rlen == 0) {
                         errno = EINTR;
 
                         return false;
                 }
 
                 buf += rlen;
                 len -= rlen;
         }
 
         return true;
 }
 
 static bool
 writeall(int fd, void *buf, size_t len)
 {
         ssize_t wlen;
 
         while (len > 0) {
                 wlen = write(fd, buf, len);
 
                 if (wlen == -1) {
                         if (errno == EINTR)
                                 continue;
 
                         return false;
                 }
 
                 buf += wlen;
                 len -= wlen;
         }
 
         return true;
 }
 
 
 /**
  * Represents a uloop task communication pipe instance, passed as sole argument
  * to the task function by {@link module:uloop#task|task()}.
  *
  * @class module:uloop.pipe
  * @hideconstructor
  *
  * @see {@link module:uloop#task|task()}
  *
  * @example *
  * const task = uloop.task((pipe) => {
  *     …
  *     pipe.send();
  *     …
  *     pipe.receive();
  *     …
  * }, …);
  */
 typedef struct {
         int input;
         int output;
         bool has_sender;
         bool has_receiver;
 } uc_uloop_pipe_t;
 
 static uc_value_t *
 uc_uloop_pipe_send_common(uc_vm_t *vm, uc_value_t *msg, int fd)
 {
         uc_stringbuf_t *buf;
         size_t len;
         bool rv;
 
         buf = xprintbuf_new();
 
         printbuf_memset(buf, 0, 0, sizeof(len));
         ucv_to_stringbuf(vm, buf, msg, true);
 
         len = printbuf_length(buf);
         memcpy(buf->buf, &len, sizeof(len));
 
         rv = writeall(fd, buf->buf, len);
 
         printbuf_free(buf);
 
         if (!rv)
                 err_return(errno);
 
         ok_return(ucv_boolean_new(true));
 }
 
 /**
  * Sends a serialized message to the task handle.
  *
  * This method serializes the provided message and sends it over the task
  * communication pipe. In the main thread, the message is deserialized and
  * passed as an argument to the output callback function registered with the
  * task handle.
  *
  * @function module:uloop.pipe#send
  *
  * @param {*} msg
  * The message to be serialized and sent over the pipe. It can be of arbitrary type.
  *
  * @returns {?boolean}
  * Returns `true` on success, indicating that the message was successfully sent
  * over the pipe. Returns `null` on error, such as when there's no output
  * callback registered with the task handle.
  *
  * @example
  * // Send a message over the uloop pipe
  * const success = pipe.send(message);
  *
  * if (success)
  *     printf("Message sent successfully\n");
  * else
  *     die(`Error sending message: ${uloop.error()}\n`);
  */
 static uc_value_t *
 uc_uloop_pipe_send(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_pipe_t *pipe = uc_fn_thisval("uloop.pipe");
         uc_value_t *msg = uc_fn_arg(0);
 
         if (!pipe)
                 err_return(EINVAL);
 
         if (!pipe->has_receiver)
                 err_return(EPIPE);
 
         ok_return(uc_uloop_pipe_send_common(vm, msg, pipe->output));
 }
 
 static bool
 uc_uloop_pipe_receive_common(uc_vm_t *vm, int fd, uc_value_t **res, bool skip)
 {
         enum json_tokener_error err = json_tokener_error_parse_eof;
         json_tokener *tok = NULL;
         json_object *jso = NULL;
         char buf[1024];
         ssize_t rlen;
         size_t len;
 
         *res = NULL;
 
         if (!readall(fd, &len, sizeof(len)))
                 err_return(errno);
 
         /* message length 0 is special, means input requested on other pipe */
         if (len == 0)
                 err_return(ENODATA);
 
         /* valid messages should be at least sizeof(len) plus one byte of payload */
         if (len <= sizeof(len))
                 err_return(EINVAL);
 
         len -= sizeof(len);
 
         while (len > 0) {
                 rlen = read(fd, buf, len < sizeof(buf) ? len : sizeof(buf));
 
                 if (rlen == -1) {
                         if (errno == EINTR)
                                 continue;
 
                         goto read_fail;
                 }
 
                 /* premature EOF */
                 if (rlen == 0) {
                         errno = EPIPE;
                         goto read_fail;
                 }
 
                 if (!skip) {
                         if (!tok)
                                 tok = xjs_new_tokener();
 
                         jso = json_tokener_parse_ex(tok, buf, rlen);
                         err = json_tokener_get_error(tok);
                 }
 
                 len -= rlen;
         }
 
         if (!skip) {
                 if (err == json_tokener_continue) {
                         jso = json_tokener_parse_ex(tok, "\0", 1);
                         err = json_tokener_get_error(tok);
                 }
 
                 json_tokener_free(tok);
 
                 if (err != json_tokener_success) {
                         errno = EINVAL;
                         goto read_fail;
                 }
 
                 *res = ucv_from_json(vm, jso);
 
                 json_object_put(jso);
         }
 
         return true;
 
 read_fail:
         if (tok)
                 json_tokener_free(tok);
 
         json_object_put(jso);
         err_return(errno);
 }
 
 /**
  * Reads input from the task handle.
  *
  * This method reads input from the task communication pipe. The input callback
  * function registered with the task handle is invoked to return the input data,
  * which is then serialized, sent over the pipe, and deserialized by the receive
  * method.
  *
  * @function module:uloop.pipe#receive
  *
  * @returns {?*}
  * Returns the deserialized message read from the task communication pipe.
  * Returns `null` on error, such as when there's no input callback registered
  * on the task handle.
  *
  * @example
  * // Read input from the task communication pipe
  * const message = pipe.receive();
  *
  * if (message !== null)
  *     printf("Received message: %s\n", message);
  * else
  *     die(`Error receiving message: ${uloop.error()}\n`);
  */
 static uc_value_t *
 uc_uloop_pipe_receive(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_pipe_t *pipe = uc_fn_thisval("uloop.pipe");
         uc_value_t *rv;
         size_t len = 0;
 
         if (!pipe)
                 err_return(EINVAL);
 
         if (!pipe->has_sender)
                 err_return(EPIPE);
 
         /* send zero-length message to signal input request */
         writeall(pipe->output, &len, sizeof(len));
 
         /* receive input message */
         uc_uloop_pipe_receive_common(vm, pipe->input, &rv, false);
 
         return rv;
 }
 
 /**
  * Checks if the task handle provides input.
  *
  * This method checks if the task handle has an input callback  registered.
  * It returns a boolean value indicating whether an input callback is present.
  *
  * @function module:uloop.pipe#sending
  *
  * @returns {boolean}
  * Returns `true` if the remote task handle has an input callback
  * registered, otherwise returns `false`.
  *
  * @example
  * // Check if the remote task handle has an input callback
  * const hasInputCallback = pipe.sending();
  *
  * if (hasInputCallback)
  *     printf("Input callback is registered on task handle\n");
  * else
  *     printf("No input callback on the task handle\n");
  */
 static uc_value_t *
 uc_uloop_pipe_sending(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_pipe_t *pipe = uc_fn_thisval("uloop.pipe");
 
         if (!pipe)
                 err_return(EINVAL);
 
         ok_return(ucv_boolean_new(pipe->has_sender));
 }
 
 /**
  * Checks if the task handle reads output.
  *
  * This method checks if the task handle has an output callback registered.
  * It returns a boolean value indicating whether an output callback is present.
  *
  * @function module:uloop.pipe#receiving
  *
  * @returns {boolean}
  * Returns `true` if the task handle has an output callback registered,
  * otherwise returns `false`.
  *
  * @example
  * // Check if the task handle has an output callback
  * const hasOutputCallback = pipe.receiving();
  *
  * if (hasOutputCallback)
  *     printf("Output callback is registered on task handle\n");
  * else
  *     printf("No output callback on the task handle\n");
  */
 static uc_value_t *
 uc_uloop_pipe_receiving(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_pipe_t *pipe = uc_fn_thisval("uloop.pipe");
 
         if (!pipe)
                 err_return(EINVAL);
 
         ok_return(ucv_boolean_new(pipe->has_receiver));
 }
 
 
 /**
  * Represents a uloop task instance as returned by
  * {@link module:uloop#task|task()}.
  *
  * @class module:uloop.task
  * @hideconstructor
  *
  * @see {@link module:uloop#task|task()}
  *
  * @example
  *
  * const task = uloop.task(…);
  *
  * task.pid();
  * task.finished();
  *
  * task.kill();
  */
 typedef struct {
         uc_uloop_cb_t cb;
         struct uloop_process process;
         struct uloop_fd output;
         bool finished;
         int input_fd;
         uc_value_t *input_cb;
         uc_value_t *output_cb;
 } uc_uloop_task_t;
 
 static int
 patch_devnull(int fd, bool write)
 {
         int devnull = open("/dev/null", write ? O_WRONLY : O_RDONLY);
 
         if (devnull != -1) {
                 dup2(fd, devnull);
                 close(fd);
         }
 
         return devnull;
 }
 
 static void
 uloop_fd_close(struct uloop_fd *fd) {
         if (fd->fd == -1)
                 return;
 
         close(fd->fd);
         fd->fd = -1;
 }
 
 static void
 uc_uloop_task_clear(uc_uloop_task_t *task)
 {
         if (task->input_fd >= 0) {
                 close(task->input_fd);
                 task->input_fd = -1;
 
                 uloop_fd_close(&task->output);
                 uloop_process_delete(&task->process);
         }
 
         uc_uloop_cb_free(&task->cb);
 }
 
 /**
  * Returns the process ID.
  *
  * This method returns the process ID (PID) of the underlying forked process
  * launched by {@link module:uloop#task|task().
  *
  * @function module:uloop.task#pid
  *
  * @returns {number}
  * The process ID (PID) of the forked task process.
  *
  * @example
  * const task = uloop.task(…);
  *
  * printf("Process ID: %d\n", task.pid());
  */
 static uc_value_t *
 uc_uloop_task_pid(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_task_t *task = uc_fn_thisval("uloop.task");
 
         if (!task)
                 err_return(EINVAL);
 
         if (task->finished)
                 err_return(ESRCH);
 
         ok_return(ucv_int64_new(task->process.pid));
 }
 
 /**
  * Terminates the task process.
  *
  * This method terminates the task process. It sends a termination signal to
  * the task process, causing it to exit. Returns `true` on success, indicating
  * that the task process was successfully terminated. Returns `null` on error,
  * such as when the task process has already terminated.
  *
  * @function module:uloop.task#kill
  *
  * @returns {?boolean}
  * Returns `true` when the task process was successfully terminated.
  * Returns `null` on error, such as when the process has already terminated.
  *
  * @example
  * // Terminate the task process
  * const success = task.kill();
  *
  * if (success)
  *     printf("Task process terminated successfully\n");
  * else
  *     die(`Error terminating task process: ${uloop.error()}\n`);
  */
 static uc_value_t *
 uc_uloop_task_kill(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_task_t *task = uc_fn_thisval("uloop.task");
         int rv;
 
         if (!task)
                 err_return(EINVAL);
 
         if (task->finished)
                 err_return(ESRCH);
 
         rv = kill(task->process.pid, SIGTERM);
 
         if (rv == -1)
                 err_return(errno);
 
         ok_return(ucv_boolean_new(true));
 }
 
 /**
  * Checks if the task ran to completion.
  *
  * This method checks if the task function has already run to completion.
  * It returns a boolean value indicating whether the task function has finished
  * executing.
  *
  * @function module:uloop.task#finished
  *
  * @returns {boolean}
  * Returns `true` if the task function has already run to completion, otherwise
  * returns `false`.
  *
  * @example
  * // Check if the task function has finished executing
  * const isFinished = task.finished();
  *
  * if (isFinished)
  *     printf("Task function has finished executing\n");
  * else
  *     printf("Task function is still running\n");
  */
 static uc_value_t *
 uc_uloop_task_finished(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_task_t *task = uc_fn_thisval("uloop.task");
 
         if (!task)
                 err_return(EINVAL);
 
         ok_return(ucv_boolean_new(task->finished));
 }
 
 static void
 uc_uloop_task_output_cb(struct uloop_fd *fd, unsigned int flags)
 {
         uc_uloop_task_t *task = container_of(fd, uc_uloop_task_t, output);
         uc_value_t *obj = task->cb.obj;
         uc_vm_t *vm = task->cb.vm;
         uc_value_t *msg = NULL;
 
         if (flags & ULOOP_READ) {
                 while (true) {
                         if (!uc_uloop_pipe_receive_common(vm, fd->fd, &msg, !task->output_cb)) {
                                 /* input requested */
                                 if (last_error == ENODATA) {
                                         uc_vm_stack_push(vm, ucv_get(obj));
                                         uc_vm_stack_push(vm, ucv_get(task->input_cb));
 
                                         if (!uc_uloop_vm_call(vm, true, 0))
                                                 return;
 
                                         msg = uc_vm_stack_pop(vm);
                                         uc_uloop_pipe_send_common(vm, msg, task->input_fd);
                                         ucv_put(msg);
 
                                         continue;
                                 }
 
                                 /* error */
                                 break;
                         }
 
                         if (task->output_cb) {
                                 uc_vm_stack_push(vm, ucv_get(obj));
                                 uc_vm_stack_push(vm, ucv_get(task->output_cb));
                                 uc_vm_stack_push(vm, msg);
 
                                 if (!uc_uloop_vm_call(vm, true, 1))
                                         return;
 
                                 ucv_put(uc_vm_stack_pop(vm));
                         }
                         else {
                                 ucv_put(msg);
                         }
                 }
         }
 
         if (!fd->registered && task->finished)
                 uc_uloop_task_clear(task);
 }
 
 static void
 uc_uloop_task_process_cb(struct uloop_process *proc, int exitcode)
 {
         uc_uloop_task_t *task = container_of(proc, uc_uloop_task_t, process);
 
         task->finished = true;
 
         uc_uloop_task_output_cb(&task->output, ULOOP_READ);
 }
 
 /**
  * Creates a task instance for executing background tasks.
  *
  * This function creates a task instance for executing background tasks.
  * It takes the task function to be invoked as a background process,
  * an optional output callback function to be invoked when output is received
  * from the task, and an optional input callback function to be invoked
  * when input is required by the task.
  *
  * @function module:uloop#task
  *
  * @param {Function} taskFunction
  * The task function to be invoked as a background process.
  *
  * @param {Function} [outputCallback]
  * Optional. The output callback function to be invoked when output is received
  * from the task. It is invoked with the output data as the argument.
  *
  * @param {Function} [inputCallback]
  * Optional. The input callback function to be invoked when input is required
  * by the task. It is invoked with a function to send input to the task
  * as the argument.
  *
  * @returns {?module:uloop.task}
  * Returns a task instance for executing background tasks.
  * Returns `null` on error, e.g. due to fork failure or invalid arguments.
  *
  * @example
  * // Create a task instance for executing a background task
  * const myTask = uloop.task(
  *     (pipe) => {
  *         // Task logic
  *         pipe.send("Hello from the task\n");
  *         const input = pipe.receive();
  *         printf(`Received input from main thread: ${input}\n`);
  *     },
  *     (output) => {
  *         // Output callback, invoked when task function calls pipe.send()
  *         printf(`Received output from task: ${output}\n`);
  *     },
  *     () => {
  *         // Input callback, invoked when task function calls pipe.receive()
  *         return "Input from main thread\n";
  *     }
  * );
  */
 static uc_value_t *
 uc_uloop_task(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *func = uc_fn_arg(0);
         uc_value_t *output_cb = uc_fn_arg(1);
         uc_value_t *input_cb = uc_fn_arg(2);
         int outpipe[2] = { -1, -1 };
         int inpipe[2] = { -1, -1 };
         uc_value_t *res, *cbs, *p;
         uc_uloop_pipe_t *tpipe;
         uc_uloop_task_t *task;
         pid_t pid;
         int err;
 
         if (!ucv_is_callable(func) ||
             (output_cb && !ucv_is_callable(output_cb)) ||
             (input_cb && !ucv_is_callable(input_cb)))
             err_return(EINVAL);
 
         if (pipe(outpipe) == -1 || pipe(inpipe) == -1) {
                 err = errno;
 
                 close(outpipe[0]); close(outpipe[1]);
                 close(inpipe[0]); close(inpipe[1]);
 
                 err_return(err);
         }
 
         pid = fork();
 
         if (pid == -1)
                 err_return(errno);
 
         if (pid == 0) {
                 uloop_done();
 
                 patch_devnull(0, false);
                 patch_devnull(1, true);
                 patch_devnull(2, true);
 
                 vm->output = fdopen(1, "w");
 
                 close(inpipe[1]);
                 close(outpipe[0]);
 
                 tpipe = xalloc(sizeof(*tpipe));
                 tpipe->input = inpipe[0];
                 tpipe->output = outpipe[1];
                 tpipe->has_sender = input_cb;
                 tpipe->has_receiver = output_cb;
 
                 p = ucv_resource_create(vm, "uloop.pipe", tpipe);
 
                 uc_vm_stack_push(vm, func);
                 uc_vm_stack_push(vm, ucv_get(p));
 
                 if (uc_uloop_vm_call(vm, false, 1)) {
                         res = uc_vm_stack_pop(vm);
                         uc_uloop_pipe_send_common(vm, res, tpipe->output);
                         ucv_put(res);
                 }
 
                 ucv_put(p);
 
                 _exit(0);
         }
 
         close(inpipe[0]);
         close(outpipe[1]);
 
         task = uc_uloop_alloc(vm, "uloop.task", sizeof(*task), func);
         task->process.pid = pid;
         task->process.cb = uc_uloop_task_process_cb;
 
         task->output.fd = outpipe[0];
         task->output.cb = uc_uloop_task_output_cb;
         task->output_cb = output_cb;
         uloop_fd_add(&task->output, ULOOP_READ);
 
         if (input_cb) {
                 task->input_fd = inpipe[1];
                 task->input_cb = input_cb;
         }
         else {
                 task->input_fd = -1;
                 close(inpipe[1]);
         }
 
         uloop_process_add(&task->process);
 
         cbs = ucv_array_new(NULL);
         ucv_array_set(cbs, 0, ucv_get(output_cb));
         ucv_array_set(cbs, 1, ucv_get(input_cb));
         ucv_resource_value_set(task->cb.obj, 1, ucv_get(cbs));
 
         ok_return(task->cb.obj);
 }
 
 
 /**
  * Represents a uloop interval timer instance as returned by
  * {@link module:uloop#interval|interval()}.
  *
  * @class module:uloop.interval
  * @hideconstructor
  *
  * @see {@link module:uloop#interval|interval()}
  *
  * @example
  *
  * const intv = uloop.interval(…);
  *
  * intv.set(…);
  * intv.remaining();
  * intv.expirations();
  * intv.cancel();
  */
 #ifdef HAVE_ULOOP_INTERVAL
 typedef struct {
         uc_uloop_cb_t cb;
         struct uloop_interval interval;
 } uc_uloop_interval_t;
 
 static int
 uc_uloop_interval_clear(uc_uloop_interval_t *interval)
 {
         int rv = uloop_interval_cancel(&interval->interval);
 
         uc_uloop_cb_free(&interval->cb);
 
         return rv;
 }
 
 /**
  * Rearms the uloop interval timer with the specified interval.
  *
  * This method rearms the interval timer with the specified interval value,
  * allowing it to trigger repeatedly after the specified amount of time. If no
  * interval value is provided or if the provided value is negative, the interval
  * remains disabled until rearmed with a positive interval value.
  *
  * @function module:uloop.interval#set
  *
  * @param {number} [interval=-1]
  * Optional. The interval value in milliseconds specifying when the interval
  * triggers again. Defaults to -1, which disables the interval until rearmed
  * with a positive interval value.
  *
  * @returns {?boolean}
  * Returns `true` on success, `null` on error, such as an invalid interval argument.
  *
  * @example
  * // Rearm the uloop interval with a interval of 1000 milliseconds
  * const success = interval.set(1000);
  *
  * if (success)
  *     printf("Interval rearmed successfully\n");
  * else
  *     printf("Error occurred while rearming interval: ${uloop.error()}\n");
  *
  * // Disable the uloop interval
  * const success = interval.set();
  *
  * if (success)
  *     printf("Interval disabled successfully\n");
  * else
  *     printf("Error occurred while disabling interval: ${uloop.error()}\n");
  */
 static uc_value_t *
 uc_uloop_interval_set(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_interval_t *interval = uc_fn_thisval("uloop.interval");
         uc_value_t *timeout = uc_fn_arg(0);
         int t, rv;
 
         if (!interval)
                 err_return(EINVAL);
 
         errno = 0;
         t = timeout ? (int)ucv_int64_get(timeout) : -1;
 
         if (errno)
                 err_return(errno);
 
         rv = uloop_interval_set(&interval->interval, t);
 
         ok_return(ucv_boolean_new(rv == 0));
 }
 
 /**
  * Returns the milliseconds until the next expiration.
  *
  * This method returns the remaining time until the uloop interval expires
  * and triggers again. If the interval is not armed (i.e., disabled),
  * it returns -1.
  *
  * @function module:uloop.interval#remaining
  *
  * @returns {number}
  * The milliseconds until the next expiration of the uloop interval, or -1 if
  * the interval is not armed.
  *
  * @example
  * // Get the milliseconds until the next expiration of the uloop interval
  * const remainingTime = interval.remaining();
  *
  * if (remainingTime !== -1)
  *     printf("Milliseconds until next expiration: %d\n", remainingTime);
  * else
  *     printf("Interval is not armed\n");
  */
 static uc_value_t *
 uc_uloop_interval_remaining(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_interval_t *interval = uc_fn_thisval("uloop.interval");
 
         if (!interval)
                 err_return(EINVAL);
 
         ok_return(ucv_int64_new(uloop_interval_remaining(&interval->interval)));
 }
 
 /**
  * Returns number of times the interval timer fired.
  *
  * This method returns the number of times the uloop interval timer has expired
  * (fired) since it was instantiated.
  *
  * @function module:uloop.interval#expirations
  *
  * @returns {number}
  * The number of times the uloop interval timer has expired (fired).
  *
  * @example
  * // Get the number of times the uloop interval timer has expired
  * const expirations = interval.expirations();
  * printf("Number of expirations: %d\n", expirations);
  */
 static uc_value_t *
 uc_uloop_interval_expirations(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_interval_t *interval = uc_fn_thisval("uloop.interval");
 
         if (!interval)
                 err_return(EINVAL);
 
         ok_return(ucv_int64_new(interval->interval.expirations));
 }
 
 /**
  * Cancels the uloop interval.
  *
  * This method cancels the uloop interval, disarming it and removing it from the
  * event loop. Associated resources are released.
  *
  * @function module:uloop.interval#cancel
  *
  * @returns {boolean}
  * Returns `true` on success.
  *
  * @example
  * // Cancel the uloop interval
  * interval.cancel();
  */
 static uc_value_t *
 uc_uloop_interval_cancel(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_interval_t *interval = uc_fn_thisval("uloop.interval");
         int rv;
 
         if (!interval)
                 err_return(EINVAL);
 
         rv = uc_uloop_interval_clear(interval);
 
         ok_return(ucv_boolean_new(rv == 0));
 }
 
 static void
 uc_uloop_interval_cb(struct uloop_interval *uintv)
 {
         uc_uloop_interval_t *interval = container_of(uintv, uc_uloop_interval_t, interval);
 
         uc_uloop_cb_invoke(&interval->cb, NULL);
 }
 
 /**
  * Creates an interval instance for scheduling repeated callbacks.
  *
  * This function creates an interval instance for scheduling repeated callbacks
  * to be executed at regular intervals. It takes an optional timeout parameter,
  * which defaults to -1, indicating that the interval is initially not armed
  * and can be armed later with the `.set(timeout)` method. A callback function
  * must be provided to be executed when the interval expires.
  *
  * @function module:uloop#interval
  *
  * @param {number} [timeout=-1]
  * Optional. The interval duration in milliseconds. Defaults to -1, indicating
  * the interval is not initially armed.
  *
  * @param {Function} callback
  * The callback function to be executed when the interval expires.
  *
  * @returns {?module:uloop.interval}
  * Returns an interval instance for scheduling repeated callbacks.
  * Returns `null` when the timeout or callback arguments are invalid.
  *
  * @example
  * // Create an interval with a callback to be executed every 1000 milliseconds
  * const myInterval = uloop.interval(1000, () => {
  *     printf("Interval callback executed!\n");
  * });
  *
  * // Later arm the interval to start executing the callback every 500 milliseconds
  * myInterval.set(500);
  */
 static uc_value_t *
 uc_uloop_interval(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *timeout = uc_fn_arg(0);
         uc_value_t *callback = uc_fn_arg(1);
         uc_uloop_interval_t *interval;
         int t;
 
         errno = 0;
         t = timeout ? ucv_int64_get(timeout) : -1;
 
         if (errno)
                 err_return(errno);
 
         if (!ucv_is_callable(callback))
                 err_return(EINVAL);
 
         interval = uc_uloop_alloc(vm, "uloop.interval", sizeof(*interval), callback);
         interval->interval.cb = uc_uloop_interval_cb;
         if (t >= 0)
                 uloop_interval_set(&interval->interval, t);
 
         ok_return(interval->cb.obj);
 }
 #endif
 
 
 /**
  * Represents a uloop signal Unix process signal handler as returned by
  * {@link module:uloop#signal|signal()}.
  *
  * @class module:uloop.signal
  * @hideconstructor
  *
  * @see {@link module:uloop#signal|signal()}
  *
  * @example
  *
  * const sighandler = uloop.signal(…);
  *
  * sighandler.signo();
  * sighandler.delete();
  */
 #ifdef HAVE_ULOOP_SIGNAL
 typedef struct {
         uc_uloop_cb_t cb;
         struct uloop_signal signal;
 } uc_uloop_signal_t;
 
 static int
 uc_uloop_signal_clear(uc_uloop_signal_t *signal)
 {
         int rv = uloop_signal_delete(&signal->signal);
 
         uc_uloop_cb_free(&signal->cb);
 
         return rv;
 }
 
 /**
  * Returns the associated signal number.
  *
  * This method returns the signal number that this uloop signal handler is
  * configured to respond to.
  *
  * @function module:uloop.signal#signo
  *
  * @returns {number}
  * The signal number that this handler is responding to.
  *
  * @example
  * // Get the signal number that the uloop signal handler is responding to
  * const sighandler = uloop.signal("SIGINT", () => printf("Cought INT\n"));
  * printf("Signal number: %d\n", sighandler.signo());
  */
 static uc_value_t *
 uc_uloop_signal_signo(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_signal_t *signal = uc_fn_thisval("uloop.signal");
 
         if (!signal)
                 err_return(EINVAL);
 
         ok_return(ucv_int64_new(signal->signal.signo));
 }
 
 /**
  * Uninstalls the signal handler.
  *
  * This method uninstalls the signal handler, restoring the previous or default
  * handler for the signal, and releasing any associated resources.
  *
  * @function module:uloop.signal#delete
  *
  * @returns {boolean}
  * Returns `true` on success.
  *
  * @example
  * // Uninstall the signal handler and restore the previous/default handler
  * const sighandler = uloop.signal(…);
  * sighandler.delete();
  */
 static uc_value_t *
 uc_uloop_signal_delete(uc_vm_t *vm, size_t nargs)
 {
         uc_uloop_signal_t *signal = uc_fn_thisval("uloop.signal");
         int rv;
 
         if (!signal)
                 err_return(EINVAL);
 
         rv = uc_uloop_signal_clear(signal);
 
         if (rv != 0)
                 err_return(EINVAL);
 
         ok_return(ucv_boolean_new(true));
 }
 
 static void
 uc_uloop_signal_cb(struct uloop_signal *usig)
 {
         uc_uloop_signal_t *signal = container_of(usig, uc_uloop_signal_t, signal);
 
         uc_uloop_cb_invoke(&signal->cb, NULL);
 }
 
 static int
 parse_signo(uc_value_t *sigspec)
 {
         if (ucv_type(sigspec) == UC_STRING) {
                 const char *signame = ucv_string_get(sigspec);
 
                 if (!strncasecmp(signame, "SIG", 3))
                         signame += 3;
 
                 for (size_t i = 0; i < UC_SYSTEM_SIGNAL_COUNT; i++) {
                         if (!uc_system_signal_names[i])
                                 continue;
 
                         if (strcasecmp(uc_system_signal_names[i], signame))
                                 continue;
 
                         return i;
                 }
         }
 
         uc_value_t *signum = ucv_to_number(sigspec);
         int64_t signo = ucv_int64_get(signum);
         ucv_put(signum);
 
         if (signo < 1 || signo >= UC_SYSTEM_SIGNAL_COUNT)
                 return -1;
 
         return signo;
 }
 
 /**
  * Creates a signal instance for handling Unix signals.
  *
  * This function creates a signal instance for handling Unix signals.
  * It takes the signal name string (with or without "SIG" prefix) or signal
  * number, and a callback function to be invoked when the specified Unix signal
  * is caught.
  *
  * @function module:uloop#signal
  *
  * @param {string|number} signal
  * The signal name string (with or without "SIG" prefix) or signal number.
  *
  * @param {Function} callback
  * The callback function to be invoked when the specified Unix signal is caught.
  *
  * @returns {?module:uloop.signal}
  * Returns a signal instance representing the installed signal handler.
  * Returns `null` when the signal or callback arguments are invalid.
  *
  * @example
  * // Create a signal instance for handling SIGINT
  * const mySignal = uloop.signal("SIGINT", () => {
  *     printf("SIGINT caught!\n");
  * });
  */
 static uc_value_t *
 uc_uloop_signal(uc_vm_t *vm, size_t nargs)
 {
         int signo = parse_signo(uc_fn_arg(0));
         uc_value_t *callback = uc_fn_arg(1);
         uc_uloop_signal_t *signal;
 
         if (signo == -1 || !ucv_is_callable(callback))
                 err_return(EINVAL);
 
         signal = uc_uloop_alloc(vm, "uloop.signal", sizeof(*signal), callback);
         signal->signal.signo = signo;
         signal->signal.cb = uc_uloop_signal_cb;
 
         uloop_signal_add(&signal->signal);
 
         ok_return(signal->cb.obj);
 }
 #endif
 
 static uc_value_t *
 uc_uloop_guard(uc_vm_t *vm, size_t nargs)
 {
         uc_value_t *arg = uc_fn_arg(0);
 
         if (!nargs)
                 return ucv_get(uc_vm_registry_get(vm, "uloop.ex_handler"));
 
         if (arg && !ucv_is_callable(arg))
                 return NULL;
 
         uc_vm_registry_set(vm, "uloop.ex_handler", ucv_get(arg));
 
         return ucv_boolean_new(true);
 }
 
 
 static const uc_function_list_t timer_fns[] = {
         { "set",                uc_uloop_timer_set },
         { "remaining",  uc_uloop_timer_remaining },
         { "cancel",             uc_uloop_timer_cancel },
 };
 
 static const uc_function_list_t handle_fns[] = {
         { "fileno",             uc_uloop_handle_fileno },
         { "handle",             uc_uloop_handle_handle },
         { "delete",             uc_uloop_handle_delete },
 };
 
 static const uc_function_list_t process_fns[] = {
         { "pid",                uc_uloop_process_pid },
         { "delete",             uc_uloop_process_delete },
 };
 
 static const uc_function_list_t task_fns[] = {
         { "pid",                uc_uloop_task_pid },
         { "kill",               uc_uloop_task_kill },
         { "finished",   uc_uloop_task_finished },
 };
 
 static const uc_function_list_t pipe_fns[] = {
         { "send",               uc_uloop_pipe_send },
         { "receive",    uc_uloop_pipe_receive },
         { "sending",    uc_uloop_pipe_sending },
         { "receiving",  uc_uloop_pipe_receiving },
 };
 
 #ifdef HAVE_ULOOP_INTERVAL
 static const uc_function_list_t interval_fns[] = {
         { "set",                uc_uloop_interval_set },
         { "remaining",  uc_uloop_interval_remaining },
         { "expirations",
                                         uc_uloop_interval_expirations },
         { "cancel",             uc_uloop_interval_cancel },
 };
 #endif
 
 #ifdef HAVE_ULOOP_SIGNAL
 static const uc_function_list_t signal_fns[] = {
         { "signo",              uc_uloop_signal_signo },
         { "delete",             uc_uloop_signal_delete },
 };
 #endif
 
 static const uc_function_list_t global_fns[] = {
         { "error",              uc_uloop_error },
         { "init",               uc_uloop_init },
         { "run",                uc_uloop_run },
         { "timer",              uc_uloop_timer },
         { "handle",             uc_uloop_handle },
         { "process",    uc_uloop_process },
         { "task",               uc_uloop_task },
         { "cancelling", uc_uloop_cancelling },
         { "running",    uc_uloop_running },
         { "done",               uc_uloop_done },
         { "end",                uc_uloop_end },
 #ifdef HAVE_ULOOP_INTERVAL
         { "interval",   uc_uloop_interval },
 #endif
 #ifdef HAVE_ULOOP_SIGNAL
         { "signal",             uc_uloop_signal },
 #endif
         { "guard",              uc_uloop_guard },
 };
 
 
 static void close_timer(void *ud)
 {
         uc_uloop_timeout_clear(ud);
 }
 
 static void close_handle(void *ud)
 {
         uc_uloop_handle_clear(ud);
 }
 
 static void close_process(void *ud)
 {
         uc_uloop_process_clear(ud);
 }
 
 static void close_task(void *ud)
 {
         uc_uloop_task_clear(ud);
 }
 
 static void close_pipe(void *ud)
 {
         uc_uloop_pipe_t *pipe = ud;
 
         if (!pipe)
                 return;
 
         close(pipe->input);
         close(pipe->output);
 
         free(pipe);
 }
 
 #ifdef HAVE_ULOOP_INTERVAL
 static void close_interval(void *ud)
 {
         uc_uloop_interval_clear(ud);
 }
 #endif
 
 #ifdef HAVE_ULOOP_SIGNAL
 static void close_signal(void *ud)
 {
         uc_uloop_signal_clear(ud);
 }
 #endif
 
 
 static struct {
         struct uloop_fd ufd;
         uc_vm_t *vm;
 } signal_handle;
 
 static void
 uc_uloop_vm_signal_cb(struct uloop_fd *ufd, unsigned int events)
 {
         if (uc_vm_signal_dispatch(signal_handle.vm) != EXCEPTION_NONE)
                 uloop_end();
 }
 
 void uc_module_init(uc_vm_t *vm, uc_value_t *scope)
 {
         int signal_fd;
 
         uc_function_list_register(scope, global_fns);
 
 #define ADD_CONST(x) ucv_object_add(scope, #x, ucv_int64_new(x))
 
         /**
          * @typedef
          * @name Event Mode Constants
          * @description
          * The `ULOOP_*` constants are passed as bitwise OR-ed number to the
          * {@link module:uloop.handle#handle|handle()} function to specify the IO
          * events that should be monitored on the given handle.
          * @property {number} ULOOP_READ - File or socket is readable.
          * @property {number} ULOOP_WRITE - File or socket is writable.
          * @property {number} ULOOP_EDGE_TRIGGER - Enable edge-triggered event mode.
          * @property {number} ULOOP_BLOCKING - Do not make descriptor non-blocking.
          */
         ADD_CONST(ULOOP_READ);
         ADD_CONST(ULOOP_WRITE);
         ADD_CONST(ULOOP_EDGE_TRIGGER);
         ADD_CONST(ULOOP_BLOCKING);
 
         uc_type_declare(vm, "uloop.timer", timer_fns, close_timer);
         uc_type_declare(vm, "uloop.handle", handle_fns, close_handle);
         uc_type_declare(vm, "uloop.process", process_fns, close_process);
         uc_type_declare(vm, "uloop.task", task_fns, close_task);
         uc_type_declare(vm, "uloop.pipe", pipe_fns, close_pipe);
 
 #ifdef HAVE_ULOOP_INTERVAL
         uc_type_declare(vm, "uloop.interval", interval_fns, close_interval);
 #endif
 
 #ifdef HAVE_ULOOP_SIGNAL
         uc_type_declare(vm, "uloop.signal", signal_fns, close_signal);
 #endif
 
         signal_fd = uc_vm_signal_notifyfd(vm);
 
         if (signal_fd != -1 && uloop_init() == 0) {
                 signal_handle.vm = vm;
                 signal_handle.ufd.cb = uc_uloop_vm_signal_cb;
                 signal_handle.ufd.fd = signal_fd;
 
                 uloop_fd_add(&signal_handle.ufd, ULOOP_READ);
         }
 }
 

• Git
• Wiki