File Content: scheduler.h #ifndef RUBY_FIBER_SCHEDULER_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_FIBER_SCHEDULER_H /** * @file * @author Ruby developers <ruby-core@ruby-lang.org> * @copyright This file is a part of the programming language Ruby. * Permission is hereby granted, to either redistribute and/or * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. * @brief Scheduler APIs. */ #include "ruby/internal/config.h" #include <errno.h> #ifdef STDC_HEADERS #include <stddef.h> /* size_t */ #endif #include "ruby/ruby.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/arithmetic.h" RBIMPL_SYMBOL_EXPORT_BEGIN() struct timeval; /** * Wrap a `ssize_t` and `int errno` into a single `VALUE`. This interface should * be used to safely capture results from system calls like `read` and `write`. * * You should use `rb_fiber_scheduler_io_result_apply` to unpack the result of * this value and update `int errno`. * * You should not directly try to interpret the result value as it is considered * an opaque representation. However, the general representation is an integer * in the range of `[-int errno, size_t size]`. Linux generally restricts the * result of system calls like `read` and `write` to `<= 2^31` which means this * will typically fit within a single FIXNUM. * * @param[in] result The result of the system call. * @param[in] error The value of `errno`. * @return A `VALUE` which contains the result and/or errno. */ static inline VALUE rb_fiber_scheduler_io_result(ssize_t result, int error) { if (result == -1) { return RB_INT2NUM(-error); } else { return RB_SIZE2NUM(result); } } /** * Apply an io result to the local thread, returning the value of the original * system call that created it and updating `int errno`. * * You should not directly try to interpret the result value as it is considered * an opaque representation. * * @param[in] result The `VALUE` which contains an errno and/or result size. * @post Updates `int errno` with the value if negative. * @return The original result of the system call. */ static inline ssize_t rb_fiber_scheduler_io_result_apply(VALUE result) { if (RB_FIXNUM_P(result) && RB_NUM2INT(result) < 0) { errno = -RB_NUM2INT(result); return -1; } else { return RB_NUM2SIZE(result); } } /** * Queries the current scheduler of the current thread that is calling this * function. * * @retval RUBY_Qnil No scheduler has been set so far to this thread (which * is the default). * @retval otherwise The scheduler that was last set for the current thread * with rb_fiber_scheduler_set(). */ VALUE rb_fiber_scheduler_get(void); /** * Destructively assigns the passed scheduler to that of the current thread * that is calling this function. If the scheduler is set, non-blocking fibers * (created by `Fiber.new` with `blocking: false`, or by `Fiber.schedule`) call * that scheduler's hook methods on potentially blocking operations, and the * current thread will call scheduler's `#close` method on finalisation * (allowing the scheduler to properly manage all non-finished fibers). * `scheduler` can be an object of any class corresponding to * `Fiber::SchedulerInterface`. Its implementation is up to the user. * * @param[in] scheduler The scheduler to set. * @exception rb_eArgError `scheduler` does not conform the interface. * @post Current thread's scheduler is `scheduler`. */ VALUE rb_fiber_scheduler_set(VALUE scheduler); /** * Identical to rb_fiber_scheduler_get(), except it also returns ::RUBY_Qnil in * case of a blocking fiber. As blocking fibers do not participate schedulers' * scheduling this function can be handy. * * @retval RUBY_Qnil No scheduler is in effect. * @retval otherwise The scheduler that is in effect, if any. */ VALUE rb_fiber_scheduler_current(void); /** * Identical to rb_fiber_scheduler_current(), except it queries for that of the * passed thread instead of the implicit current one. * * @param[in] thread Target thread. * @exception rb_eTypeError `thread` is not a thread. * @retval RUBY_Qnil No scheduler is in effect in `thread`. * @retval otherwise The scheduler that is in effect in `thread`. */ VALUE rb_fiber_scheduler_current_for_thread(VALUE thread); /** * Converts the passed timeout to an expression that rb_fiber_scheduler_block() * etc. expects. * * @param[in] timeout A duration (can be `NULL`). * @retval RUBY_Qnil No timeout (blocks indefinitely). * @retval otherwise A timeout object. */ VALUE rb_fiber_scheduler_make_timeout(struct timeval *timeout); /** * Closes the passed scheduler object. This expects the scheduler to wait for * all fibers. Thus the scheduler's main loop tends to start here. * * @param[in] scheduler Target scheduler. * @return What `scheduler.close` returns. */ VALUE rb_fiber_scheduler_close(VALUE scheduler); /** * Nonblocking `sleep`. Depending on scheduler implementation, this for * instance switches to another fiber etc. * * @param[in] scheduler Target scheduler. * @param[in] duration Passed as-is to `scheduler.kernel_sleep`. * @return What `scheduler.kernel_sleep` returns. */ VALUE rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE duration); /** * Identical to rb_fiber_scheduler_kernel_sleep(), except it can pass multiple * arguments. * * @param[in] scheduler Target scheduler. * @param[in] argc Number of objects of `argv`. * @param[in] argv Passed as-is to `scheduler.kernel_sleep` * @return What `scheduler.kernel_sleep` returns. */ VALUE rb_fiber_scheduler_kernel_sleepv(VALUE scheduler, int argc, VALUE * argv); /* Description TBW */ #if 0 VALUE rb_fiber_scheduler_timeout_after(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message); VALUE rb_fiber_scheduler_timeout_afterv(VALUE scheduler, int argc, VALUE * argv); int rb_fiber_scheduler_supports_process_wait(VALUE scheduler); #endif /** * Nonblocking `waitpid`. Depending on scheduler implementation, this for * instance switches to another fiber etc. * * @param[in] scheduler Target scheduler. * @param[in] pid Process ID to wait. * @param[in] flags Wait flags, e.g. `WUNTRACED`. * @return What `scheduler.process_wait` returns. */ VALUE rb_fiber_scheduler_process_wait(VALUE scheduler, rb_pid_t pid, int flags); /** * Nonblocking wait for the passed "blocker", which is for instance * `Thread.join` or `Mutex.lock`. Depending on scheduler implementation, this * for instance switches to another fiber etc. * * @param[in] scheduler Target scheduler. * @param[in] blocker What blocks the current fiber. * @param[in] timeout Numeric timeout. * @return What `scheduler.block` returns. */ VALUE rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout); /** * Wakes up a fiber previously blocked using rb_fiber_scheduler_block(). * * @param[in] scheduler Target scheduler. * @param[in] blocker What was awaited for. * @param[in] fiber What to unblock. * @return What `scheduler.unblock` returns. */ VALUE rb_fiber_scheduler_unblock(VALUE scheduler, VALUE blocker, VALUE fiber); /** * Nonblocking version of rb_io_wait(). Depending on scheduler implementation, * this for instance switches to another fiber etc. * * The "events" here is a Ruby level integer, which is an OR-ed value of * `IO::READABLE`, `IO::WRITABLE`, and `IO::PRIORITY`. * * @param[in] scheduler Target scheduler. * @param[in] io An io object to wait. * @param[in] events An integer set of interests. * @param[in] timeout Numeric timeout. * @return What `scheduler.io_wait` returns. */ VALUE rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout); /** * Nonblocking wait until the passed IO is ready for reading. This is a * special case of rb_fiber_scheduler_io_wait(), where the interest is * `IO::READABLE` and timeout is never. * * @param[in] scheduler Target scheduler. * @param[in] io An io object to wait. * @return What `scheduler.io_wait` returns. */ VALUE rb_fiber_scheduler_io_wait_readable(VALUE scheduler, VALUE io); /** * Nonblocking wait until the passed IO is ready for writing. This is a * special case of rb_fiber_scheduler_io_wait(), where the interest is * `IO::WRITABLE` and timeout is never. * * @param[in] scheduler Target scheduler. * @param[in] io An io object to wait. * @return What `scheduler.io_wait` returns. */ VALUE rb_fiber_scheduler_io_wait_writable(VALUE scheduler, VALUE io); /** * Nonblocking read from the passed IO. * * @param[in] scheduler Target scheduler. * @param[out] io An io object to read from. * @param[out] buffer Return buffer. * @param[in] length Requested number of bytes to read. * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. * @return otherwise What `scheduler.io_read` returns `[-errno, size]`. */ VALUE rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t length); /** * Nonblocking write to the passed IO. * * @param[in] scheduler Target scheduler. * @param[out] io An io object to write to. * @param[in] buffer What to write. * @param[in] length Number of bytes to write. * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. * @return otherwise What `scheduler.io_write` returns `[-errno, size]`. */ VALUE rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t length); /** * Nonblocking read from the passed IO at the specified offset. * * @param[in] scheduler Target scheduler. * @param[out] io An io object to read from. * @param[out] buffer Return buffer. * @param[in] length Requested number of bytes to read. * @param[in] offset The offset in the given IO to read the data from. * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. * @return otherwise What `scheduler.io_read` returns. */ VALUE rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, VALUE buffer, size_t length, off_t offset); /** * Nonblocking write to the passed IO at the specified offset. * * @param[in] scheduler Target scheduler. * @param[out] io An io object to write to. * @param[in] buffer What to write. * @param[in] length Number of bytes to write. * @param[in] offset The offset in the given IO to write the data to. * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. * @return otherwise What `scheduler.io_write` returns. */ VALUE rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, VALUE buffer, size_t length, off_t offset); /** * Nonblocking read from the passed IO using a native buffer. * * @param[in] scheduler Target scheduler. * @param[out] io An io object to read from. * @param[out] buffer Return buffer. * @param[in] length Requested number of bytes to read. * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. * @return otherwise What `scheduler.io_read` returns. */ VALUE rb_fiber_scheduler_io_read_memory(VALUE scheduler, VALUE io, void *buffer, size_t size, size_t length); /** * Nonblocking write to the passed IO using a native buffer. * * @param[in] scheduler Target scheduler. * @param[out] io An io object to write to. * @param[in] buffer What to write. * @param[in] length Number of bytes to write. * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. * @return otherwise What `scheduler.io_write` returns. */ VALUE rb_fiber_scheduler_io_write_memory(VALUE scheduler, VALUE io, const void *buffer, size_t size, size_t length); /** * Nonblocking close the given IO. * * @param[in] scheduler Target scheduler. * @param[in] io An io object to close. * @retval RUBY_Qundef `scheduler` doesn't have `#io_close`. * @return otherwise What `scheduler.io_close` returns. */ VALUE rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io); /** * Nonblocking DNS lookup. * * @param[in] scheduler Target scheduler. * @param[in] hostname A host name to query. * @retval RUBY_Qundef `scheduler` doesn't have `#address_resolve`. * @return otherwise What `scheduler.address_resolve` returns. */ VALUE rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname); RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_FIBER_SCHEDULER_H */ Submit