Current File : //opt/alt/ruby31/include/ruby/thread.h
#ifndef RUBY_THREAD_H /*-*-C++-*-vi:se ft=cpp:*/
#define RUBY_THREAD_H 1
/**
* @file
* @author $Author: matz $
* @date Tue Jul 10 17:35:43 JST 2012
* @copyright Copyright (C) 2007 Yukihiro Matsumoto
* @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.
*/
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/intern/thread.h" /* rb_unblock_function_t */
#include "ruby/internal/dllexport.h"
/**
* @name Flags for rb_nogvl()
*
* @{
*/
/**
* Passing this flag to rb_nogvl() prevents it from checking interrupts.
* Interrupts can impact your program negatively. For instance consider
* following callback function:
*
* ```CXX
* static inline int fd; // set elsewhere.
* static inline auto callback(auto buf) {
* auto tmp = ruby_xmalloc(BUFSIZ);
* auto ret = ruby_xmalloc(sizeof(ssize_t)); // (a)
* auto n = read(fd, tmp, BUFSIZ); // (b)
* memcpy(buf, tmp, n); // (c)
* memcpy(ret, n, sizeof(n));
* ruby_xfree(tmp);
* return ret;
* }
* ```
*
* Here, if it gets interrupted at (a) or (b), `read(2)` is cancelled and this
* function leaks memory (which is not a good thing of course, but...). But if
* it gets interrupted at (c), where `read(2)` is already done, interruption is
* way more catastrophic because what was read gets lost. To reroute this kind
* of problem you should set this flag. And check interrupts elsewhere at your
* own risk.
*/
#define RB_NOGVL_INTR_FAIL (0x1)
/**
* Passing this flag to rb_nogvl() indicates that the passed UBF is
* async-signal-safe. An UBF could be async safe, and that makes things
* simpler. However async unsafe UBFs are just okay. If unsure, you can
* safely leave it unspecified.
*
* @internal
*
* This makes sense only in case of POSIX threads.
*/
#define RB_NOGVL_UBF_ASYNC_SAFE (0x2)
/** @} */
RBIMPL_SYMBOL_EXPORT_BEGIN()
RBIMPL_ATTR_NONNULL((1))
/**
* (Re-)acquires the GVL. This manoeuvre makes it possible for an out-of-GVL
* routine to one-shot call a ruby method.
*
* What this function does:
*
* 1. Blocks until it acquires the GVL.
* 2. Calls the passed function.
* 3. Releases the GVL.
* 4. Returns what was returned form the passed function.
*
* @param[in] func What to call with GVL.
* @param[in,out] data1 Passed as-is to `func`.
* @return What was returned from `func`.
* @warning `func` must not return a Ruby object. If it did such return
* value would escape from GC's scope; would not be marked.
* @warning Global escapes from this function just yield whatever fatal
* undefined behaviours. You must make sure that `func` does
* not raise, by properly rescuing everything using
* e.g. rb_protect().
* @warning You cannot convert a non-Ruby thread into a Ruby thread
* using this API. This function makes sense only from inside
* of a rb_thread_call_without_gvl()'s callback.
*/
void *rb_thread_call_with_gvl(void *(*func)(void *), void *data1);
RBIMPL_ATTR_NONNULL((1))
/**
* Allows the passed function to run in parallel with other Ruby threads.
*
* What this function does:
*
* 1. Checks (and handles) pending interrupts.
* 2. Releases the GVL. (Others can run here in parallel...)
* 3. Calls the passed function.
* 4. Blocks until it re-acquires the GVL.
* 5. Checks interrupts that happened between 2 to 4.
*
* In case other threads interfaced with this thread using rb_thread_kill()
* etc., the passed UBF is additionally called. See ::rb_unblock_function_t
* for details.
*
* Unlike rb_thread_call_without_gvl2() this function also reacts to signals
* etc.
*
* @param[in] func A function to call without GVL.
* @param[in,out] data1 Passed as-is to `func`.
* @param[in] ubf An UBF to cancel `func`.
* @param[in,out] data2 Passed as-is to `ubf`.
* @return What `func` returned, or 0 in case `ubf` cancelled `func`.
* @warning You cannot use most of Ruby C APIs like calling methods or
* raising exceptions from any of the functions passed to it.
* If that is dead necessary use rb_thread_call_with_gvl() to
* re-acquire the GVL.
* @warning In short, this API is difficult. @ko1 recommends you to use
* other ways if any. We lack experiences to use this API. If
* you find any corner cases etc., please report it to the
* devs.
* @warning Releasing and re-acquiring the GVL are expensive operations.
* For a short-running `func`, it might be faster to just call
* `func` with blocking everything else. Be sure to benchmark
* your code to see if it is actually worth releasing the GVL.
*/
void *rb_thread_call_without_gvl(void *(*func)(void *), void *data1,
rb_unblock_function_t *ubf, void *data2);
RBIMPL_ATTR_NONNULL((1))
/**
* Identical to rb_thread_call_without_gvl(), except it does not interface with
* signals etc. As described in #RB_NOGVL_INTR_FAIL, interrupts can hurt you.
* In case this function detects an interrupt, it returns immediately. You can
* record progress of your callback and check it after returning from this
* function.
*
* What this function does:
*
* 1. Checks for pending interrupts and if any, just returns.
* 2. Releases the GVL. (Others can run here in parallel...)
* 3. Calls the passed function.
* 4. Blocks until it re-acquires the GVL.
*
* @param[in] func A function to call without GVL.
* @param[in,out] data1 Passed as-is to `func`.
* @param[in] ubf An UBF to cancel `func`.
* @param[in,out] data2 Passed as-is to `ubf`.
* @return What `func` returned, or 0 in case `func` did not return.
*/
void *rb_thread_call_without_gvl2(void *(*func)(void *), void *data1,
rb_unblock_function_t *ubf, void *data2);
/*
* XXX: unstable/unapproved - out-of-tree code should NOT not depend
* on this until it hits Ruby 2.6.1
*/
RBIMPL_ATTR_NONNULL((1))
/**
* Identical to rb_thread_call_without_gvl(), except it additionally takes
* "flags" that change the behaviour.
*
* @param[in] func A function to call without GVL.
* @param[in,out] data1 Passed as-is to `func`.
* @param[in] ubf An UBF to cancel `func`.
* @param[in,out] data2 Passed as-is to `ubf`.
* @param[in] flags Flags.
* @return What `func` returned, or 0 in case `func` did not return.
*/
void *rb_nogvl(void *(*func)(void *), void *data1,
rb_unblock_function_t *ubf, void *data2,
int flags);
/**
* @private
*
* @deprecated This macro once was a thing in the old days, but makes no sense
* any longer today. Exists here for backwards compatibility
* only. You can safely forget about it.
*/
#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01
/**
* @private
* @deprecated It seems even in the old days it made no sense...?
*/
#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_
RBIMPL_SYMBOL_EXPORT_END()
#endif /* RUBY_THREAD_H */