Edit File by line

#ifndef RUBY_THREAD_H /*-*-C++-*-vi:se ft=cpp:*/

[0] Fix | Delete

#define RUBY_THREAD_H 1

[1] Fix | Delete

/**

[2] Fix | Delete

* @file

[3] Fix | Delete

* @author $Author: matz $

[4] Fix | Delete

* @date Tue Jul 10 17:35:43 JST 2012

[5] Fix | Delete

[6] Fix | Delete

* @copyright This file is a part of the programming language Ruby.

[7] Fix | Delete

* Permission is hereby granted, to either redistribute and/or

[8] Fix | Delete

* modify this file, provided that the conditions mentioned in the

[9] Fix | Delete

* file COPYING are met. Consult the file for details.

[10] Fix | Delete

[11] Fix | Delete

#include "ruby/internal/attr/nonnull.h"

[12] Fix | Delete

#include "ruby/internal/intern/thread.h" /* rb_unblock_function_t */

[13] Fix | Delete

#include "ruby/internal/dllexport.h"

[14] Fix | Delete

[15] Fix | Delete

/**

[16] Fix | Delete

* @name Flags for rb_nogvl()

[17] Fix | Delete

[18] Fix | Delete

* @{

[19] Fix | Delete

[20] Fix | Delete

[21] Fix | Delete

/**

[22] Fix | Delete

* Passing this flag to rb_nogvl() prevents it from checking interrupts.

[23] Fix | Delete

* Interrupts can impact your program negatively. For instance consider

[24] Fix | Delete

* following callback function:

[25] Fix | Delete

[26] Fix | Delete

* ```CXX

[27] Fix | Delete

* static inline int fd; // set elsewhere.

[28] Fix | Delete

* static inline auto callback(auto buf) {

[29] Fix | Delete

* auto tmp = ruby_xmalloc(BUFSIZ);

[30] Fix | Delete

* auto ret = ruby_xmalloc(sizeof(ssize_t)); // (a)

[31] Fix | Delete

* auto n = read(fd, tmp, BUFSIZ); // (b)

[32] Fix | Delete

* memcpy(buf, tmp, n); // (c)

[33] Fix | Delete

* memcpy(ret, n, sizeof(n));

[34] Fix | Delete

* ruby_xfree(tmp);

[35] Fix | Delete

* return ret;

[36] Fix | Delete

* }

[37] Fix | Delete

* ```

[38] Fix | Delete

[39] Fix | Delete

* Here, if it gets interrupted at (a) or (b), `read(2)` is cancelled and this

[40] Fix | Delete

* function leaks memory (which is not a good thing of course, but...). But if

[41] Fix | Delete

* it gets interrupted at (c), where `read(2)` is already done, interruption is

[42] Fix | Delete

* way more catastrophic because what was read gets lost. To reroute this kind

[43] Fix | Delete

* of problem you should set this flag. And check interrupts elsewhere at your

[44] Fix | Delete

* own risk.

[45] Fix | Delete

[46] Fix | Delete

#define RB_NOGVL_INTR_FAIL (0x1)

[47] Fix | Delete

[48] Fix | Delete

/**

[49] Fix | Delete

* Passing this flag to rb_nogvl() indicates that the passed UBF is

[50] Fix | Delete

* async-signal-safe. An UBF could be async safe, and that makes things

[51] Fix | Delete

* simpler. However async unsafe UBFs are just okay. If unsure, you can

[52] Fix | Delete

* safely leave it unspecified.

[53] Fix | Delete

[54] Fix | Delete

* @internal

[55] Fix | Delete

[56] Fix | Delete

* This makes sense only in case of POSIX threads.

[57] Fix | Delete

[58] Fix | Delete

#define RB_NOGVL_UBF_ASYNC_SAFE (0x2)

[59] Fix | Delete

[60] Fix | Delete

/** @} */

[61] Fix | Delete

[62] Fix | Delete

RBIMPL_SYMBOL_EXPORT_BEGIN()

[63] Fix | Delete

[64] Fix | Delete

RBIMPL_ATTR_NONNULL((1))

[65] Fix | Delete

/**

[66] Fix | Delete

* (Re-)acquires the GVL. This manoeuvre makes it possible for an out-of-GVL

[67] Fix | Delete

* routine to one-shot call a ruby method.

[68] Fix | Delete

[69] Fix | Delete

* What this function does:

[70] Fix | Delete

[71] Fix | Delete

* 1. Blocks until it acquires the GVL.

[72] Fix | Delete

* 2. Calls the passed function.

[73] Fix | Delete

* 3. Releases the GVL.

[74] Fix | Delete

* 4. Returns what was returned form the passed function.

[75] Fix | Delete

[76] Fix | Delete

* @param[in] func What to call with GVL.

[77] Fix | Delete

* @param[in,out] data1 Passed as-is to `func`.

[78] Fix | Delete

* @return What was returned from `func`.

[79] Fix | Delete

* @warning `func` must not return a Ruby object. If it did such return

[80] Fix | Delete

* value would escape from GC's scope; would not be marked.

[81] Fix | Delete

* @warning Global escapes from this function just yield whatever fatal

[82] Fix | Delete

* undefined behaviours. You must make sure that `func` does

[83] Fix | Delete

* not raise, by properly rescuing everything using

[84] Fix | Delete

* e.g. rb_protect().

[85] Fix | Delete

* @warning You cannot convert a non-Ruby thread into a Ruby thread

[86] Fix | Delete

* using this API. This function makes sense only from inside

[87] Fix | Delete

* of a rb_thread_call_without_gvl()'s callback.

[88] Fix | Delete

[89] Fix | Delete

void *rb_thread_call_with_gvl(void *(*func)(void *), void *data1);

[90] Fix | Delete

[91] Fix | Delete

RBIMPL_ATTR_NONNULL((1))

[92] Fix | Delete

/**

[93] Fix | Delete

* Allows the passed function to run in parallel with other Ruby threads.

[94] Fix | Delete

[95] Fix | Delete

* What this function does:

[96] Fix | Delete

[97] Fix | Delete

* 1. Checks (and handles) pending interrupts.

[98] Fix | Delete

* 2. Releases the GVL. (Others can run here in parallel...)

[99] Fix | Delete

* 3. Calls the passed function.

[100] Fix | Delete

* 4. Blocks until it re-acquires the GVL.

[101] Fix | Delete

* 5. Checks interrupts that happened between 2 to 4.

[102] Fix | Delete

[103] Fix | Delete

* In case other threads interfaced with this thread using rb_thread_kill()

[104] Fix | Delete

* etc., the passed UBF is additionally called. See ::rb_unblock_function_t

[105] Fix | Delete

* for details.

[106] Fix | Delete

[107] Fix | Delete

* Unlike rb_thread_call_without_gvl2() this function also reacts to signals

[108] Fix | Delete

* etc.

[109] Fix | Delete

[110] Fix | Delete

* @param[in] func A function to call without GVL.

[111] Fix | Delete

* @param[in,out] data1 Passed as-is to `func`.

[112] Fix | Delete

* @param[in] ubf An UBF to cancel `func`.

[113] Fix | Delete

* @param[in,out] data2 Passed as-is to `ubf`.

[114] Fix | Delete

* @return What `func` returned, or 0 in case `ubf` cancelled `func`.

[115] Fix | Delete

* @warning You cannot use most of Ruby C APIs like calling methods or

[116] Fix | Delete

* raising exceptions from any of the functions passed to it.

[117] Fix | Delete

* If that is dead necessary use rb_thread_call_with_gvl() to

[118] Fix | Delete

* re-acquire the GVL.

[119] Fix | Delete

* @warning In short, this API is difficult. @ko1 recommends you to use

[120] Fix | Delete

* other ways if any. We lack experiences to use this API. If

[121] Fix | Delete

* you find any corner cases etc., please report it to the

[122] Fix | Delete

* devs.

[123] Fix | Delete

* @warning Releasing and re-acquiring the GVL are expensive operations.

[124] Fix | Delete

* For a short-running `func`, it might be faster to just call

[125] Fix | Delete

* `func` with blocking everything else. Be sure to benchmark

[126] Fix | Delete

* your code to see if it is actually worth releasing the GVL.

[127] Fix | Delete

[128] Fix | Delete

void *rb_thread_call_without_gvl(void *(*func)(void *), void *data1,

[129] Fix | Delete

rb_unblock_function_t *ubf, void *data2);

[130] Fix | Delete

[131] Fix | Delete

RBIMPL_ATTR_NONNULL((1))

[132] Fix | Delete

/**

[133] Fix | Delete

* Identical to rb_thread_call_without_gvl(), except it does not interface with

[134] Fix | Delete

* signals etc. As described in #RB_NOGVL_INTR_FAIL, interrupts can hurt you.

[135] Fix | Delete

* In case this function detects an interrupt, it returns immediately. You can

[136] Fix | Delete

* record progress of your callback and check it after returning from this

[137] Fix | Delete

* function.

[138] Fix | Delete

[139] Fix | Delete

* What this function does:

[140] Fix | Delete

[141] Fix | Delete

* 1. Checks for pending interrupts and if any, just returns.

[142] Fix | Delete

* 2. Releases the GVL. (Others can run here in parallel...)

[143] Fix | Delete

* 3. Calls the passed function.

[144] Fix | Delete

* 4. Blocks until it re-acquires the GVL.

[145] Fix | Delete

[146] Fix | Delete

* @param[in] func A function to call without GVL.

[147] Fix | Delete

* @param[in,out] data1 Passed as-is to `func`.

[148] Fix | Delete

* @param[in] ubf An UBF to cancel `func`.

[149] Fix | Delete

* @param[in,out] data2 Passed as-is to `ubf`.

[150] Fix | Delete

* @return What `func` returned, or 0 in case `func` did not return.

[151] Fix | Delete

[152] Fix | Delete

void *rb_thread_call_without_gvl2(void *(*func)(void *), void *data1,

[153] Fix | Delete

rb_unblock_function_t *ubf, void *data2);

[154] Fix | Delete

[155] Fix | Delete

[156] Fix | Delete

* XXX: unstable/unapproved - out-of-tree code should NOT not depend

[157] Fix | Delete

* on this until it hits Ruby 2.6.1

[158] Fix | Delete

[159] Fix | Delete

[160] Fix | Delete

RBIMPL_ATTR_NONNULL((1))

[161] Fix | Delete

/**

[162] Fix | Delete

* Identical to rb_thread_call_without_gvl(), except it additionally takes

[163] Fix | Delete

* "flags" that change the behaviour.

[164] Fix | Delete

[165] Fix | Delete

* @param[in] func A function to call without GVL.

[166] Fix | Delete

* @param[in,out] data1 Passed as-is to `func`.

[167] Fix | Delete

* @param[in] ubf An UBF to cancel `func`.

[168] Fix | Delete

* @param[in,out] data2 Passed as-is to `ubf`.

[169] Fix | Delete

* @param[in] flags Flags.

[170] Fix | Delete

* @return What `func` returned, or 0 in case `func` did not return.

[171] Fix | Delete

[172] Fix | Delete

void *rb_nogvl(void *(*func)(void *), void *data1,

[173] Fix | Delete

rb_unblock_function_t *ubf, void *data2,

[174] Fix | Delete

int flags);

[175] Fix | Delete

[176] Fix | Delete

/**

[177] Fix | Delete

* @private

[178] Fix | Delete

[179] Fix | Delete

* @deprecated This macro once was a thing in the old days, but makes no sense

[180] Fix | Delete

* any longer today. Exists here for backwards compatibility

[181] Fix | Delete

* only. You can safely forget about it.

[182] Fix | Delete

[183] Fix | Delete

#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01

[184] Fix | Delete

[185] Fix | Delete

/**

[186] Fix | Delete

* @private

[187] Fix | Delete

* @deprecated It seems even in the old days it made no sense...?

[188] Fix | Delete

[189] Fix | Delete

#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_

[190] Fix | Delete

[191] Fix | Delete

RBIMPL_SYMBOL_EXPORT_END()

[192] Fix | Delete

[193] Fix | Delete

#endif /* RUBY_THREAD_H */

[194] Fix | Delete

[195] Fix | Delete