1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
#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 */
|
