1 /**********************************************************************
6 created at: Thu May 23 09:03:43 2007
8 Copyright (C) 2007 Koichi Sasada
10 **********************************************************************/
12 #include "ruby/internal/config.h"
19 // On Solaris, madvise() is NOT declared for SUS (XPG4v2) or later,
20 // but MADV_* macros are defined when __EXTENSIONS__ is defined.
21 #ifdef NEED_MADVICE_PROTOTYPE_USING_CADDR_T
22 #include <sys/types.h>
23 extern int madvise(caddr_t
, size_t, int);
28 #include "eval_intern.h"
31 #include "internal/cont.h"
32 #include "internal/proc.h"
33 #include "internal/warnings.h"
34 #include "ruby/fiber/scheduler.h"
38 #include "ractor_core.h"
40 static const int DEBUG
= 0;
42 #define RB_PAGE_SIZE (pagesize)
43 #define RB_PAGE_MASK (~(RB_PAGE_SIZE - 1))
46 static const rb_data_type_t cont_data_type
, fiber_data_type
;
47 static VALUE rb_cContinuation
;
48 static VALUE rb_cFiber
;
49 static VALUE rb_eFiberError
;
50 #ifdef RB_EXPERIMENTAL_FIBER_POOL
51 static VALUE rb_cFiberPool
;
54 #define CAPTURE_JUST_VALID_VM_STACK 1
56 // Defined in `coroutine/$arch/Context.h`:
57 #ifdef COROUTINE_LIMITED_ADDRESS_SPACE
58 #define FIBER_POOL_ALLOCATION_FREE
59 #define FIBER_POOL_INITIAL_SIZE 8
60 #define FIBER_POOL_ALLOCATION_MAXIMUM_SIZE 32
62 #define FIBER_POOL_INITIAL_SIZE 32
63 #define FIBER_POOL_ALLOCATION_MAXIMUM_SIZE 1024
67 CONTINUATION_CONTEXT
= 0,
71 struct cont_saved_vm_stack
{
73 #ifdef CAPTURE_JUST_VALID_VM_STACK
74 size_t slen
; /* length of stack (head of ec->vm_stack) */
75 size_t clen
; /* length of control frames (tail of ec->vm_stack) */
81 // Represents a single stack.
82 struct fiber_pool_stack
{
83 // A pointer to the memory allocation (lowest address) for the stack.
86 // The current stack pointer, taking into account the direction of the stack.
89 // The size of the stack excluding any guard pages.
92 // The available stack capacity w.r.t. the current stack offset.
95 // The pool this stack should be allocated from.
96 struct fiber_pool
* pool
;
98 // If the stack is allocated, the allocation it came from.
99 struct fiber_pool_allocation
* allocation
;
102 // A linked list of vacant (unused) stacks.
103 // This structure is stored in the first page of a stack if it is not in use.
104 // @sa fiber_pool_vacancy_pointer
105 struct fiber_pool_vacancy
{
106 // Details about the vacant stack:
107 struct fiber_pool_stack stack
;
109 // The vacancy linked list.
110 #ifdef FIBER_POOL_ALLOCATION_FREE
111 struct fiber_pool_vacancy
* previous
;
113 struct fiber_pool_vacancy
* next
;
116 // Manages singly linked list of mapped regions of memory which contains 1 more more stack:
118 // base = +-------------------------------+-----------------------+ +
119 // |VM Stack |VM Stack | | |
122 // +-------------------------------+ | |
123 // |Machine Stack |Machine Stack | | |
126 // | | | . . . . | | size
132 // +-------------------------------+ | |
133 // |Guard Page |Guard Page | | |
134 // +-------------------------------+-----------------------+ v
136 // +------------------------------------------------------->
140 struct fiber_pool_allocation
{
141 // A pointer to the memory mapped region.
144 // The size of the individual stacks.
147 // The stride of individual stacks (including any guard pages or other accounting details).
150 // The number of stacks that were allocated.
153 #ifdef FIBER_POOL_ALLOCATION_FREE
154 // The number of stacks used in this allocation.
158 struct fiber_pool
* pool
;
160 // The allocation linked list.
161 #ifdef FIBER_POOL_ALLOCATION_FREE
162 struct fiber_pool_allocation
* previous
;
164 struct fiber_pool_allocation
* next
;
167 // A fiber pool manages vacant stacks to reduce the overhead of creating fibers.
169 // A singly-linked list of allocations which contain 1 or more stacks each.
170 struct fiber_pool_allocation
* allocations
;
172 // Provides O(1) stack "allocation":
173 struct fiber_pool_vacancy
* vacancies
;
175 // The size of the stack allocations (excluding any guard page).
178 // The total number of stacks that have been allocated in this pool.
181 // The initial number of stacks to allocate.
182 size_t initial_count
;
184 // Whether to madvise(free) the stack or not:
187 // The number of stacks that have been used in this pool.
190 // The amount to allocate for the vm_stack:
191 size_t vm_stack_size
;
194 typedef struct rb_context_struct
{
195 enum context_type type
;
201 struct cont_saved_vm_stack saved_vm_stack
;
208 rb_execution_context_t saved_ec
;
210 rb_ensure_entry_t
*ensure_array
;
211 /* Pointer to MJIT info about the continuation. */
212 struct mjit_cont
*mjit_cont
;
218 * [Fiber.new] ------> FIBER_CREATED
221 * +--> FIBER_RESUMED ----+
222 * [Fiber#resume] | | [Fiber.yield] |
224 * +-- FIBER_SUSPENDED | [Terminate]
226 * FIBER_TERMINATED <-+
235 #define FIBER_CREATED_P(fiber) ((fiber)->status == FIBER_CREATED)
236 #define FIBER_RESUMED_P(fiber) ((fiber)->status == FIBER_RESUMED)
237 #define FIBER_SUSPENDED_P(fiber) ((fiber)->status == FIBER_SUSPENDED)
238 #define FIBER_TERMINATED_P(fiber) ((fiber)->status == FIBER_TERMINATED)
239 #define FIBER_RUNNABLE_P(fiber) (FIBER_CREATED_P(fiber) || FIBER_SUSPENDED_P(fiber))
241 struct rb_fiber_struct
{
244 struct rb_fiber_struct
*prev
;
245 struct rb_fiber_struct
*resuming_fiber
;
247 BITFIELD(enum fiber_status
, status
, 2);
248 /* Whether the fiber is allowed to implicitly yield. */
249 unsigned int yielding
: 1;
250 unsigned int blocking
: 1;
252 struct coroutine_context context
;
253 struct fiber_pool_stack stack
;
256 static struct fiber_pool shared_fiber_pool
= {NULL
, NULL
, 0, 0, 0, 0};
258 static ID fiber_initialize_keywords
[2] = {0};
261 * FreeBSD require a first (i.e. addr) argument of mmap(2) is not NULL
262 * if MAP_STACK is passed.
263 * http://www.FreeBSD.org/cgi/query-pr.cgi?pr=158755
265 #if defined(MAP_STACK) && !defined(__FreeBSD__) && !defined(__FreeBSD_kernel__)
266 #define FIBER_STACK_FLAGS (MAP_PRIVATE | MAP_ANON | MAP_STACK)
268 #define FIBER_STACK_FLAGS (MAP_PRIVATE | MAP_ANON)
271 #define ERRNOMSG strerror(errno)
273 // Locates the stack vacancy details for the given stack.
274 // Requires that fiber_pool_vacancy fits within one page.
275 inline static struct fiber_pool_vacancy
*
276 fiber_pool_vacancy_pointer(void * base
, size_t size
)
278 STACK_GROW_DIR_DETECTION
;
280 return (struct fiber_pool_vacancy
*)(
281 (char*)base
+ STACK_DIR_UPPER(0, size
- RB_PAGE_SIZE
)
285 // Reset the current stack pointer and available size of the given stack.
287 fiber_pool_stack_reset(struct fiber_pool_stack
* stack
)
289 STACK_GROW_DIR_DETECTION
;
291 stack
->current
= (char*)stack
->base
+ STACK_DIR_UPPER(0, stack
->size
);
292 stack
->available
= stack
->size
;
295 // A pointer to the base of the current unused portion of the stack.
297 fiber_pool_stack_base(struct fiber_pool_stack
* stack
)
299 STACK_GROW_DIR_DETECTION
;
301 VM_ASSERT(stack
->current
);
303 return STACK_DIR_UPPER(stack
->current
, (char*)stack
->current
- stack
->available
);
306 // Allocate some memory from the stack. Used to allocate vm_stack inline with machine stack.
307 // @sa fiber_initialize_coroutine
309 fiber_pool_stack_alloca(struct fiber_pool_stack
* stack
, size_t offset
)
311 STACK_GROW_DIR_DETECTION
;
313 if (DEBUG
) fprintf(stderr
, "fiber_pool_stack_alloca(%p): %"PRIuSIZE
"/%"PRIuSIZE
"\n", (void*)stack
, offset
, stack
->available
);
314 VM_ASSERT(stack
->available
>= offset
);
316 // The pointer to the memory being allocated:
317 void * pointer
= STACK_DIR_UPPER(stack
->current
, (char*)stack
->current
- offset
);
319 // Move the stack pointer:
320 stack
->current
= STACK_DIR_UPPER((char*)stack
->current
+ offset
, (char*)stack
->current
- offset
);
321 stack
->available
-= offset
;
326 // Reset the current stack pointer and available size of the given stack.
328 fiber_pool_vacancy_reset(struct fiber_pool_vacancy
* vacancy
)
330 fiber_pool_stack_reset(&vacancy
->stack
);
332 // Consume one page of the stack because it's used for the vacancy list:
333 fiber_pool_stack_alloca(&vacancy
->stack
, RB_PAGE_SIZE
);
336 inline static struct fiber_pool_vacancy
*
337 fiber_pool_vacancy_push(struct fiber_pool_vacancy
* vacancy
, struct fiber_pool_vacancy
* head
)
339 vacancy
->next
= head
;
341 #ifdef FIBER_POOL_ALLOCATION_FREE
343 head
->previous
= vacancy
;
344 vacancy
->previous
= NULL
;
351 #ifdef FIBER_POOL_ALLOCATION_FREE
353 fiber_pool_vacancy_remove(struct fiber_pool_vacancy
* vacancy
)
356 vacancy
->next
->previous
= vacancy
->previous
;
359 if (vacancy
->previous
) {
360 vacancy
->previous
->next
= vacancy
->next
;
363 // It's the head of the list:
364 vacancy
->stack
.pool
->vacancies
= vacancy
->next
;
368 inline static struct fiber_pool_vacancy
*
369 fiber_pool_vacancy_pop(struct fiber_pool
* pool
)
371 struct fiber_pool_vacancy
* vacancy
= pool
->vacancies
;
374 fiber_pool_vacancy_remove(vacancy
);
380 inline static struct fiber_pool_vacancy
*
381 fiber_pool_vacancy_pop(struct fiber_pool
* pool
)
383 struct fiber_pool_vacancy
* vacancy
= pool
->vacancies
;
386 pool
->vacancies
= vacancy
->next
;
393 // Initialize the vacant stack. The [base, size] allocation should not include the guard page.
394 // @param base The pointer to the lowest address of the allocated memory.
395 // @param size The size of the allocated memory.
396 inline static struct fiber_pool_vacancy
*
397 fiber_pool_vacancy_initialize(struct fiber_pool
* fiber_pool
, struct fiber_pool_vacancy
* vacancies
, void * base
, size_t size
)
399 struct fiber_pool_vacancy
* vacancy
= fiber_pool_vacancy_pointer(base
, size
);
401 vacancy
->stack
.base
= base
;
402 vacancy
->stack
.size
= size
;
404 fiber_pool_vacancy_reset(vacancy
);
406 vacancy
->stack
.pool
= fiber_pool
;
408 return fiber_pool_vacancy_push(vacancy
, vacancies
);
411 // Allocate a maximum of count stacks, size given by stride.
412 // @param count the number of stacks to allocate / were allocated.
413 // @param stride the size of the individual stacks.
414 // @return [void *] the allocated memory or NULL if allocation failed.
416 fiber_pool_allocate_memory(size_t * count
, size_t stride
)
418 // We use a divide-by-2 strategy to try and allocate memory. We are trying
419 // to allocate `count` stacks. In normal situation, this won't fail. But
420 // if we ran out of address space, or we are allocating more memory than
421 // the system would allow (e.g. overcommit * physical memory + swap), we
422 // divide count by two and try again. This condition should only be
423 // encountered in edge cases, but we handle it here gracefully.
426 void * base
= VirtualAlloc(0, (*count
)*stride
, MEM_COMMIT
, PAGE_READWRITE
);
429 *count
= (*count
) >> 1;
436 void * base
= mmap(NULL
, (*count
)*stride
, PROT_READ
| PROT_WRITE
, FIBER_STACK_FLAGS
, -1, 0);
438 if (base
== MAP_FAILED
) {
439 // If the allocation fails, count = count / 2, and try again.
440 *count
= (*count
) >> 1;
443 #if defined(MADV_FREE_REUSE)
444 // On Mac MADV_FREE_REUSE is necessary for the task_info api
445 // to keep the accounting accurate as possible when a page is marked as reusable
446 // it can possibly not occurring at first call thus re-iterating if necessary.
447 while (madvise(base
, (*count
)*stride
, MADV_FREE_REUSE
) == -1 && errno
== EAGAIN
);
457 // Given an existing fiber pool, expand it by the specified number of stacks.
458 // @param count the maximum number of stacks to allocate.
459 // @return the allocated fiber pool.
460 // @sa fiber_pool_allocation_free
461 static struct fiber_pool_allocation
*
462 fiber_pool_expand(struct fiber_pool
* fiber_pool
, size_t count
)
464 STACK_GROW_DIR_DETECTION
;
466 size_t size
= fiber_pool
->size
;
467 size_t stride
= size
+ RB_PAGE_SIZE
;
469 // Allocate the memory required for the stacks:
470 void * base
= fiber_pool_allocate_memory(&count
, stride
);
473 rb_raise(rb_eFiberError
, "can't alloc machine stack to fiber (%"PRIuSIZE
" x %"PRIuSIZE
" bytes): %s", count
, size
, ERRNOMSG
);
476 struct fiber_pool_vacancy
* vacancies
= fiber_pool
->vacancies
;
477 struct fiber_pool_allocation
* allocation
= RB_ALLOC(struct fiber_pool_allocation
);
479 // Initialize fiber pool allocation:
480 allocation
->base
= base
;
481 allocation
->size
= size
;
482 allocation
->stride
= stride
;
483 allocation
->count
= count
;
484 #ifdef FIBER_POOL_ALLOCATION_FREE
485 allocation
->used
= 0;
487 allocation
->pool
= fiber_pool
;
490 fprintf(stderr
, "fiber_pool_expand(%"PRIuSIZE
"): %p, %"PRIuSIZE
"/%"PRIuSIZE
" x [%"PRIuSIZE
":%"PRIuSIZE
"]\n",
491 count
, (void*)fiber_pool
, fiber_pool
->used
, fiber_pool
->count
, size
, fiber_pool
->vm_stack_size
);
494 // Iterate over all stacks, initializing the vacancy list:
495 for (size_t i
= 0; i
< count
; i
+= 1) {
496 void * base
= (char*)allocation
->base
+ (stride
* i
);
497 void * page
= (char*)base
+ STACK_DIR_UPPER(size
, 0);
502 if (!VirtualProtect(page
, RB_PAGE_SIZE
, PAGE_READWRITE
| PAGE_GUARD
, &old_protect
)) {
503 VirtualFree(allocation
->base
, 0, MEM_RELEASE
);
504 rb_raise(rb_eFiberError
, "can't set a guard page: %s", ERRNOMSG
);
507 if (mprotect(page
, RB_PAGE_SIZE
, PROT_NONE
) < 0) {
508 munmap(allocation
->base
, count
*stride
);
509 rb_raise(rb_eFiberError
, "can't set a guard page: %s", ERRNOMSG
);
513 vacancies
= fiber_pool_vacancy_initialize(
514 fiber_pool
, vacancies
,
515 (char*)base
+ STACK_DIR_UPPER(0, RB_PAGE_SIZE
),
519 #ifdef FIBER_POOL_ALLOCATION_FREE
520 vacancies
->stack
.allocation
= allocation
;
524 // Insert the allocation into the head of the pool:
525 allocation
->next
= fiber_pool
->allocations
;
527 #ifdef FIBER_POOL_ALLOCATION_FREE
528 if (allocation
->next
) {
529 allocation
->next
->previous
= allocation
;
532 allocation
->previous
= NULL
;
535 fiber_pool
->allocations
= allocation
;
536 fiber_pool
->vacancies
= vacancies
;
537 fiber_pool
->count
+= count
;
542 // Initialize the specified fiber pool with the given number of stacks.
543 // @param vm_stack_size The size of the vm stack to allocate.
545 fiber_pool_initialize(struct fiber_pool
* fiber_pool
, size_t size
, size_t count
, size_t vm_stack_size
)
547 VM_ASSERT(vm_stack_size
< size
);
549 fiber_pool
->allocations
= NULL
;
550 fiber_pool
->vacancies
= NULL
;
551 fiber_pool
->size
= ((size
/ RB_PAGE_SIZE
) + 1) * RB_PAGE_SIZE
;
552 fiber_pool
->count
= 0;
553 fiber_pool
->initial_count
= count
;
554 fiber_pool
->free_stacks
= 1;
555 fiber_pool
->used
= 0;
557 fiber_pool
->vm_stack_size
= vm_stack_size
;
559 fiber_pool_expand(fiber_pool
, count
);
562 #ifdef FIBER_POOL_ALLOCATION_FREE
563 // Free the list of fiber pool allocations.
565 fiber_pool_allocation_free(struct fiber_pool_allocation
* allocation
)
567 STACK_GROW_DIR_DETECTION
;
569 VM_ASSERT(allocation
->used
== 0);
571 if (DEBUG
) fprintf(stderr
, "fiber_pool_allocation_free: %p base=%p count=%"PRIuSIZE
"\n", (void*)allocation
, allocation
->base
, allocation
->count
);
574 for (i
= 0; i
< allocation
->count
; i
+= 1) {
575 void * base
= (char*)allocation
->base
+ (allocation
->stride
* i
) + STACK_DIR_UPPER(0, RB_PAGE_SIZE
);
577 struct fiber_pool_vacancy
* vacancy
= fiber_pool_vacancy_pointer(base
, allocation
->size
);
579 // Pop the vacant stack off the free list:
580 fiber_pool_vacancy_remove(vacancy
);
584 VirtualFree(allocation
->base
, 0, MEM_RELEASE
);
586 munmap(allocation
->base
, allocation
->stride
* allocation
->count
);
589 if (allocation
->previous
) {
590 allocation
->previous
->next
= allocation
->next
;
593 // We are the head of the list, so update the pool:
594 allocation
->pool
->allocations
= allocation
->next
;
597 if (allocation
->next
) {
598 allocation
->next
->previous
= allocation
->previous
;
601 allocation
->pool
->count
-= allocation
->count
;
603 ruby_xfree(allocation
);
607 // Acquire a stack from the given fiber pool. If none are available, allocate more.
608 static struct fiber_pool_stack
609 fiber_pool_stack_acquire(struct fiber_pool
* fiber_pool
)
611 struct fiber_pool_vacancy
* vacancy
= fiber_pool_vacancy_pop(fiber_pool
);
613 if (DEBUG
) fprintf(stderr
, "fiber_pool_stack_acquire: %p used=%"PRIuSIZE
"\n", (void*)fiber_pool
->vacancies
, fiber_pool
->used
);
616 const size_t maximum
= FIBER_POOL_ALLOCATION_MAXIMUM_SIZE
;
617 const size_t minimum
= fiber_pool
->initial_count
;
619 size_t count
= fiber_pool
->count
;
620 if (count
> maximum
) count
= maximum
;
621 if (count
< minimum
) count
= minimum
;
623 fiber_pool_expand(fiber_pool
, count
);
625 // The free list should now contain some stacks:
626 VM_ASSERT(fiber_pool
->vacancies
);
628 vacancy
= fiber_pool_vacancy_pop(fiber_pool
);
632 VM_ASSERT(vacancy
->stack
.base
);
634 // Take the top item from the free list:
635 fiber_pool
->used
+= 1;
637 #ifdef FIBER_POOL_ALLOCATION_FREE
638 vacancy
->stack
.allocation
->used
+= 1;
641 fiber_pool_stack_reset(&vacancy
->stack
);
643 return vacancy
->stack
;
646 // We advise the operating system that the stack memory pages are no longer being used.
647 // This introduce some performance overhead but allows system to relaim memory when there is pressure.
649 fiber_pool_stack_free(struct fiber_pool_stack
* stack
)
651 void * base
= fiber_pool_stack_base(stack
);
652 size_t size
= stack
->available
;
654 // If this is not true, the vacancy information will almost certainly be destroyed:
655 VM_ASSERT(size
<= (stack
->size
- RB_PAGE_SIZE
));
657 if (DEBUG
) fprintf(stderr
, "fiber_pool_stack_free: %p+%"PRIuSIZE
" [base=%p, size=%"PRIuSIZE
"]\n", base
, size
, stack
->base
, stack
->size
);
659 #if VM_CHECK_MODE > 0 && defined(MADV_DONTNEED)
660 // This immediately discards the pages and the memory is reset to zero.
661 madvise(base
, size
, MADV_DONTNEED
);
662 #elif defined(POSIX_MADV_DONTNEED)
663 posix_madvise(base
, size
, POSIX_MADV_DONTNEED
);
664 #elif defined(MADV_FREE_REUSABLE)
665 // Acknowledge the kernel down to the task info api we make this
666 // page reusable for future use.
667 // As for MADV_FREE_REUSE below we ensure in the rare occasions the task was not
668 // completed at the time of the call to re-iterate.
669 while (madvise(base
, size
, MADV_FREE_REUSABLE
) == -1 && errno
== EAGAIN
);
670 #elif defined(MADV_FREE)
671 madvise(base
, size
, MADV_FREE
);
672 #elif defined(MADV_DONTNEED)
673 madvise(base
, size
, MADV_DONTNEED
);
674 #elif defined(_WIN32)
675 VirtualAlloc(base
, size
, MEM_RESET
, PAGE_READWRITE
);
676 // Not available in all versions of Windows.
677 //DiscardVirtualMemory(base, size);
681 // Release and return a stack to the vacancy list.
683 fiber_pool_stack_release(struct fiber_pool_stack
* stack
)
685 struct fiber_pool
* pool
= stack
->pool
;
686 struct fiber_pool_vacancy
* vacancy
= fiber_pool_vacancy_pointer(stack
->base
, stack
->size
);
688 if (DEBUG
) fprintf(stderr
, "fiber_pool_stack_release: %p used=%"PRIuSIZE
"\n", stack
->base
, stack
->pool
->used
);
690 // Copy the stack details into the vacancy area:
691 vacancy
->stack
= *stack
;
692 // After this point, be careful about updating/using state in stack, since it's copied to the vacancy area.
694 // Reset the stack pointers and reserve space for the vacancy data:
695 fiber_pool_vacancy_reset(vacancy
);
697 // Push the vacancy into the vancancies list:
698 pool
->vacancies
= fiber_pool_vacancy_push(vacancy
, stack
->pool
->vacancies
);
701 #ifdef FIBER_POOL_ALLOCATION_FREE
702 struct fiber_pool_allocation
* allocation
= stack
->allocation
;
704 allocation
->used
-= 1;
706 // Release address space and/or dirty memory:
707 if (allocation
->used
== 0) {
708 fiber_pool_allocation_free(allocation
);
710 else if (stack
->pool
->free_stacks
) {
711 fiber_pool_stack_free(&vacancy
->stack
);
714 // This is entirely optional, but clears the dirty flag from the stack memory, so it won't get swapped to disk when there is memory pressure:
715 if (stack
->pool
->free_stacks
) {
716 fiber_pool_stack_free(&vacancy
->stack
);
722 ec_switch(rb_thread_t
*th
, rb_fiber_t
*fiber
)
724 rb_execution_context_t
*ec
= &fiber
->cont
.saved_ec
;
725 rb_ractor_set_current_ec(th
->ractor
, th
->ec
= ec
);
726 // ruby_current_execution_context_ptr = th->ec = ec;
729 * timer-thread may set trap interrupt on previous th->ec at any time;
730 * ensure we do not delay (or lose) the trap interrupt handling.
732 if (th
->vm
->ractor
.main_thread
== th
&&
733 rb_signal_buff_size() > 0) {
734 RUBY_VM_SET_TRAP_INTERRUPT(ec
);
737 VM_ASSERT(ec
->fiber_ptr
->cont
.self
== 0 || ec
->vm_stack
!= NULL
);
741 fiber_restore_thread(rb_thread_t
*th
, rb_fiber_t
*fiber
)
743 ec_switch(th
, fiber
);
744 VM_ASSERT(th
->ec
->fiber_ptr
== fiber
);
748 fiber_entry(struct coroutine_context
* from
, struct coroutine_context
* to
)
750 rb_fiber_t
*fiber
= to
->argument
;
751 rb_thread_t
*thread
= fiber
->cont
.saved_ec
.thread_ptr
;
753 #ifdef COROUTINE_PTHREAD_CONTEXT
754 ruby_thread_set_native(thread
);
757 fiber_restore_thread(thread
, fiber
);
759 rb_fiber_start(fiber
);
761 #ifndef COROUTINE_PTHREAD_CONTEXT
762 VM_UNREACHABLE(fiber_entry
);
766 // Initialize a fiber's coroutine's machine stack and vm stack.
768 fiber_initialize_coroutine(rb_fiber_t
*fiber
, size_t * vm_stack_size
)
770 struct fiber_pool
* fiber_pool
= fiber
->stack
.pool
;
771 rb_execution_context_t
*sec
= &fiber
->cont
.saved_ec
;
772 void * vm_stack
= NULL
;
774 VM_ASSERT(fiber_pool
!= NULL
);
776 fiber
->stack
= fiber_pool_stack_acquire(fiber_pool
);
777 vm_stack
= fiber_pool_stack_alloca(&fiber
->stack
, fiber_pool
->vm_stack_size
);
778 *vm_stack_size
= fiber_pool
->vm_stack_size
;
780 coroutine_initialize(&fiber
->context
, fiber_entry
, fiber_pool_stack_base(&fiber
->stack
), fiber
->stack
.available
);
782 // The stack for this execution context is the one we allocated:
783 sec
->machine
.stack_start
= fiber
->stack
.current
;
784 sec
->machine
.stack_maxsize
= fiber
->stack
.available
;
786 fiber
->context
.argument
= (void*)fiber
;
791 // Release the stack from the fiber, it's execution context, and return it to the fiber pool.
793 fiber_stack_release(rb_fiber_t
* fiber
)
795 rb_execution_context_t
*ec
= &fiber
->cont
.saved_ec
;
797 if (DEBUG
) fprintf(stderr
, "fiber_stack_release: %p, stack.base=%p\n", (void*)fiber
, fiber
->stack
.base
);
799 // Return the stack back to the fiber pool if it wasn't already:
800 if (fiber
->stack
.base
) {
801 fiber_pool_stack_release(&fiber
->stack
);
802 fiber
->stack
.base
= NULL
;
805 // The stack is no longer associated with this execution context:
806 rb_ec_clear_vm_stack(ec
);
810 fiber_status_name(enum fiber_status s
)
813 case FIBER_CREATED
: return "created";
814 case FIBER_RESUMED
: return "resumed";
815 case FIBER_SUSPENDED
: return "suspended";
816 case FIBER_TERMINATED
: return "terminated";
818 VM_UNREACHABLE(fiber_status_name
);
823 fiber_verify(const rb_fiber_t
*fiber
)
825 #if VM_CHECK_MODE > 0
826 VM_ASSERT(fiber
->cont
.saved_ec
.fiber_ptr
== fiber
);
828 switch (fiber
->status
) {
830 VM_ASSERT(fiber
->cont
.saved_ec
.vm_stack
!= NULL
);
832 case FIBER_SUSPENDED
:
833 VM_ASSERT(fiber
->cont
.saved_ec
.vm_stack
!= NULL
);
836 case FIBER_TERMINATED
:
840 VM_UNREACHABLE(fiber_verify
);
846 fiber_status_set(rb_fiber_t
*fiber
, enum fiber_status s
)
848 // if (DEBUG) fprintf(stderr, "fiber: %p, status: %s -> %s\n", (void *)fiber, fiber_status_name(fiber->status), fiber_status_name(s));
849 VM_ASSERT(!FIBER_TERMINATED_P(fiber
));
850 VM_ASSERT(fiber
->status
!= s
);
855 static rb_context_t
*
860 TypedData_Get_Struct(obj
, rb_context_t
, &cont_data_type
, cont
);
870 TypedData_Get_Struct(obj
, rb_fiber_t
, &fiber_data_type
, fiber
);
871 if (!fiber
) rb_raise(rb_eFiberError
, "uninitialized fiber");
876 NOINLINE(static VALUE
cont_capture(volatile int *volatile stat
));
878 #define THREAD_MUST_BE_RUNNING(th) do { \
879 if (!(th)->ec->tag) rb_raise(rb_eThreadError, "not running thread"); \
883 rb_fiber_threadptr(const rb_fiber_t
*fiber
)
885 return fiber
->cont
.saved_ec
.thread_ptr
;
889 cont_thread_value(const rb_context_t
*cont
)
891 return cont
->saved_ec
.thread_ptr
->self
;
895 cont_compact(void *ptr
)
897 rb_context_t
*cont
= ptr
;
900 cont
->self
= rb_gc_location(cont
->self
);
902 cont
->value
= rb_gc_location(cont
->value
);
903 rb_execution_context_update(&cont
->saved_ec
);
909 rb_context_t
*cont
= ptr
;
911 RUBY_MARK_ENTER("cont");
913 rb_gc_mark_movable(cont
->self
);
915 rb_gc_mark_movable(cont
->value
);
917 rb_execution_context_mark(&cont
->saved_ec
);
918 rb_gc_mark(cont_thread_value(cont
));
920 if (cont
->saved_vm_stack
.ptr
) {
921 #ifdef CAPTURE_JUST_VALID_VM_STACK
922 rb_gc_mark_locations(cont
->saved_vm_stack
.ptr
,
923 cont
->saved_vm_stack
.ptr
+ cont
->saved_vm_stack
.slen
+ cont
->saved_vm_stack
.clen
);
925 rb_gc_mark_locations(cont
->saved_vm_stack
.ptr
,
926 cont
->saved_vm_stack
.ptr
, cont
->saved_ec
.stack_size
);
930 if (cont
->machine
.stack
) {
931 if (cont
->type
== CONTINUATION_CONTEXT
) {
933 rb_gc_mark_locations(cont
->machine
.stack
,
934 cont
->machine
.stack
+ cont
->machine
.stack_size
);
938 const rb_fiber_t
*fiber
= (rb_fiber_t
*)cont
;
940 if (!FIBER_TERMINATED_P(fiber
)) {
941 rb_gc_mark_locations(cont
->machine
.stack
,
942 cont
->machine
.stack
+ cont
->machine
.stack_size
);
947 RUBY_MARK_LEAVE("cont");
952 fiber_is_root_p(const rb_fiber_t
*fiber
)
954 return fiber
== fiber
->cont
.saved_ec
.thread_ptr
->root_fiber
;
961 rb_context_t
*cont
= ptr
;
963 RUBY_FREE_ENTER("cont");
965 if (cont
->type
== CONTINUATION_CONTEXT
) {
966 ruby_xfree(cont
->saved_ec
.vm_stack
);
967 ruby_xfree(cont
->ensure_array
);
968 RUBY_FREE_UNLESS_NULL(cont
->machine
.stack
);
971 rb_fiber_t
*fiber
= (rb_fiber_t
*)cont
;
972 coroutine_destroy(&fiber
->context
);
973 fiber_stack_release(fiber
);
976 RUBY_FREE_UNLESS_NULL(cont
->saved_vm_stack
.ptr
);
979 VM_ASSERT(cont
->mjit_cont
!= NULL
);
980 mjit_cont_free(cont
->mjit_cont
);
982 /* free rb_cont_t or rb_fiber_t */
984 RUBY_FREE_LEAVE("cont");
988 cont_memsize(const void *ptr
)
990 const rb_context_t
*cont
= ptr
;
993 size
= sizeof(*cont
);
994 if (cont
->saved_vm_stack
.ptr
) {
995 #ifdef CAPTURE_JUST_VALID_VM_STACK
996 size_t n
= (cont
->saved_vm_stack
.slen
+ cont
->saved_vm_stack
.clen
);
998 size_t n
= cont
->saved_ec
.vm_stack_size
;
1000 size
+= n
* sizeof(*cont
->saved_vm_stack
.ptr
);
1003 if (cont
->machine
.stack
) {
1004 size
+= cont
->machine
.stack_size
* sizeof(*cont
->machine
.stack
);
1011 rb_fiber_update_self(rb_fiber_t
*fiber
)
1013 if (fiber
->cont
.self
) {
1014 fiber
->cont
.self
= rb_gc_location(fiber
->cont
.self
);
1017 rb_execution_context_update(&fiber
->cont
.saved_ec
);
1022 rb_fiber_mark_self(const rb_fiber_t
*fiber
)
1024 if (fiber
->cont
.self
) {
1025 rb_gc_mark_movable(fiber
->cont
.self
);
1028 rb_execution_context_mark(&fiber
->cont
.saved_ec
);
1033 fiber_compact(void *ptr
)
1035 rb_fiber_t
*fiber
= ptr
;
1036 fiber
->first_proc
= rb_gc_location(fiber
->first_proc
);
1038 if (fiber
->prev
) rb_fiber_update_self(fiber
->prev
);
1040 cont_compact(&fiber
->cont
);
1041 fiber_verify(fiber
);
1045 fiber_mark(void *ptr
)
1047 rb_fiber_t
*fiber
= ptr
;
1048 RUBY_MARK_ENTER("cont");
1049 fiber_verify(fiber
);
1050 rb_gc_mark_movable(fiber
->first_proc
);
1051 if (fiber
->prev
) rb_fiber_mark_self(fiber
->prev
);
1052 cont_mark(&fiber
->cont
);
1053 RUBY_MARK_LEAVE("cont");
1057 fiber_free(void *ptr
)
1059 rb_fiber_t
*fiber
= ptr
;
1060 RUBY_FREE_ENTER("fiber");
1062 if (DEBUG
) fprintf(stderr
, "fiber_free: %p[%p]\n", (void *)fiber
, fiber
->stack
.base
);
1064 if (fiber
->cont
.saved_ec
.local_storage
) {
1065 rb_id_table_free(fiber
->cont
.saved_ec
.local_storage
);
1068 cont_free(&fiber
->cont
);
1069 RUBY_FREE_LEAVE("fiber");
1073 fiber_memsize(const void *ptr
)
1075 const rb_fiber_t
*fiber
= ptr
;
1076 size_t size
= sizeof(*fiber
);
1077 const rb_execution_context_t
*saved_ec
= &fiber
->cont
.saved_ec
;
1078 const rb_thread_t
*th
= rb_ec_thread_ptr(saved_ec
);
1081 * vm.c::thread_memsize already counts th->ec->local_storage
1083 if (saved_ec
->local_storage
&& fiber
!= th
->root_fiber
) {
1084 size
+= rb_id_table_memsize(saved_ec
->local_storage
);
1086 size
+= cont_memsize(&fiber
->cont
);
1091 rb_obj_is_fiber(VALUE obj
)
1093 return RBOOL(rb_typeddata_is_kind_of(obj
, &fiber_data_type
));
1097 cont_save_machine_stack(rb_thread_t
*th
, rb_context_t
*cont
)
1101 SET_MACHINE_STACK_END(&th
->ec
->machine
.stack_end
);
1103 if (th
->ec
->machine
.stack_start
> th
->ec
->machine
.stack_end
) {
1104 size
= cont
->machine
.stack_size
= th
->ec
->machine
.stack_start
- th
->ec
->machine
.stack_end
;
1105 cont
->machine
.stack_src
= th
->ec
->machine
.stack_end
;
1108 size
= cont
->machine
.stack_size
= th
->ec
->machine
.stack_end
- th
->ec
->machine
.stack_start
;
1109 cont
->machine
.stack_src
= th
->ec
->machine
.stack_start
;
1112 if (cont
->machine
.stack
) {
1113 REALLOC_N(cont
->machine
.stack
, VALUE
, size
);
1116 cont
->machine
.stack
= ALLOC_N(VALUE
, size
);
1119 FLUSH_REGISTER_WINDOWS
;
1120 MEMCPY(cont
->machine
.stack
, cont
->machine
.stack_src
, VALUE
, size
);
1123 static const rb_data_type_t cont_data_type
= {
1125 {cont_mark
, cont_free
, cont_memsize
, cont_compact
},
1126 0, 0, RUBY_TYPED_FREE_IMMEDIATELY
1130 cont_save_thread(rb_context_t
*cont
, rb_thread_t
*th
)
1132 rb_execution_context_t
*sec
= &cont
->saved_ec
;
1134 VM_ASSERT(th
->status
== THREAD_RUNNABLE
);
1136 /* save thread context */
1139 /* saved_ec->machine.stack_end should be NULL */
1140 /* because it may happen GC afterward */
1141 sec
->machine
.stack_end
= NULL
;
1145 cont_init_mjit_cont(rb_context_t
*cont
)
1147 VM_ASSERT(cont
->mjit_cont
== NULL
);
1149 cont
->mjit_cont
= mjit_cont_new(&(cont
->saved_ec
));
1154 cont_init(rb_context_t
*cont
, rb_thread_t
*th
)
1156 /* save thread context */
1157 cont_save_thread(cont
, th
);
1158 cont
->saved_ec
.thread_ptr
= th
;
1159 cont
->saved_ec
.local_storage
= NULL
;
1160 cont
->saved_ec
.local_storage_recursive_hash
= Qnil
;
1161 cont
->saved_ec
.local_storage_recursive_hash_for_trace
= Qnil
;
1162 cont_init_mjit_cont(cont
);
1165 static rb_context_t
*
1166 cont_new(VALUE klass
)
1169 volatile VALUE contval
;
1170 rb_thread_t
*th
= GET_THREAD();
1172 THREAD_MUST_BE_RUNNING(th
);
1173 contval
= TypedData_Make_Struct(klass
, rb_context_t
, &cont_data_type
, cont
);
1174 cont
->self
= contval
;
1175 cont_init(cont
, th
);
1180 rb_fiberptr_self(struct rb_fiber_struct
*fiber
)
1182 return fiber
->cont
.self
;
1186 rb_fiberptr_blocking(struct rb_fiber_struct
*fiber
)
1188 return fiber
->blocking
;
1191 // This is used for root_fiber because other fibers call cont_init_mjit_cont through cont_new.
1193 rb_fiber_init_mjit_cont(struct rb_fiber_struct
*fiber
)
1195 cont_init_mjit_cont(&fiber
->cont
);
1200 show_vm_stack(const rb_execution_context_t
*ec
)
1202 VALUE
*p
= ec
->vm_stack
;
1203 while (p
< ec
->cfp
->sp
) {
1204 fprintf(stderr
, "%3d ", (int)(p
- ec
->vm_stack
));
1205 rb_obj_info_dump(*p
);
1211 show_vm_pcs(const rb_control_frame_t
*cfp
,
1212 const rb_control_frame_t
*end_of_cfp
)
1215 while (cfp
!= end_of_cfp
) {
1218 pc
= cfp
->pc
- cfp
->iseq
->body
->iseq_encoded
;
1220 fprintf(stderr
, "%2d pc: %d\n", i
++, pc
);
1221 cfp
= RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp
);
1225 COMPILER_WARNING_PUSH
1227 COMPILER_WARNING_IGNORED(-Wduplicate
-decl
-specifier
)
1230 cont_capture(volatile int *volatile stat
)
1232 rb_context_t
*volatile cont
;
1233 rb_thread_t
*th
= GET_THREAD();
1234 volatile VALUE contval
;
1235 const rb_execution_context_t
*ec
= th
->ec
;
1237 THREAD_MUST_BE_RUNNING(th
);
1238 rb_vm_stack_to_heap(th
->ec
);
1239 cont
= cont_new(rb_cContinuation
);
1240 contval
= cont
->self
;
1242 #ifdef CAPTURE_JUST_VALID_VM_STACK
1243 cont
->saved_vm_stack
.slen
= ec
->cfp
->sp
- ec
->vm_stack
;
1244 cont
->saved_vm_stack
.clen
= ec
->vm_stack
+ ec
->vm_stack_size
- (VALUE
*)ec
->cfp
;
1245 cont
->saved_vm_stack
.ptr
= ALLOC_N(VALUE
, cont
->saved_vm_stack
.slen
+ cont
->saved_vm_stack
.clen
);
1246 MEMCPY(cont
->saved_vm_stack
.ptr
,
1248 VALUE
, cont
->saved_vm_stack
.slen
);
1249 MEMCPY(cont
->saved_vm_stack
.ptr
+ cont
->saved_vm_stack
.slen
,
1252 cont
->saved_vm_stack
.clen
);
1254 cont
->saved_vm_stack
.ptr
= ALLOC_N(VALUE
, ec
->vm_stack_size
);
1255 MEMCPY(cont
->saved_vm_stack
.ptr
, ec
->vm_stack
, VALUE
, ec
->vm_stack_size
);
1257 // At this point, `cfp` is valid but `vm_stack` should be cleared:
1258 rb_ec_set_vm_stack(&cont
->saved_ec
, NULL
, 0);
1259 VM_ASSERT(cont
->saved_ec
.cfp
!= NULL
);
1260 cont_save_machine_stack(th
, cont
);
1262 /* backup ensure_list to array for search in another context */
1264 rb_ensure_list_t
*p
;
1266 rb_ensure_entry_t
*entry
;
1267 for (p
=th
->ec
->ensure_list
; p
; p
=p
->next
)
1269 entry
= cont
->ensure_array
= ALLOC_N(rb_ensure_entry_t
,size
+1);
1270 for (p
=th
->ec
->ensure_list
; p
; p
=p
->next
) {
1271 if (!p
->entry
.marker
)
1272 p
->entry
.marker
= rb_ary_tmp_new(0); /* dummy object */
1273 *entry
++ = p
->entry
;
1278 if (ruby_setjmp(cont
->jmpbuf
)) {
1281 VAR_INITIALIZED(cont
);
1282 value
= cont
->value
;
1283 if (cont
->argc
== -1) rb_exc_raise(value
);
1293 COMPILER_WARNING_POP
1296 cont_restore_thread(rb_context_t
*cont
)
1298 rb_thread_t
*th
= GET_THREAD();
1300 /* restore thread context */
1301 if (cont
->type
== CONTINUATION_CONTEXT
) {
1303 rb_execution_context_t
*sec
= &cont
->saved_ec
;
1304 rb_fiber_t
*fiber
= NULL
;
1306 if (sec
->fiber_ptr
!= NULL
) {
1307 fiber
= sec
->fiber_ptr
;
1309 else if (th
->root_fiber
) {
1310 fiber
= th
->root_fiber
;
1313 if (fiber
&& th
->ec
!= &fiber
->cont
.saved_ec
) {
1314 ec_switch(th
, fiber
);
1317 if (th
->ec
->trace_arg
!= sec
->trace_arg
) {
1318 rb_raise(rb_eRuntimeError
, "can't call across trace_func");
1322 #ifdef CAPTURE_JUST_VALID_VM_STACK
1323 MEMCPY(th
->ec
->vm_stack
,
1324 cont
->saved_vm_stack
.ptr
,
1325 VALUE
, cont
->saved_vm_stack
.slen
);
1326 MEMCPY(th
->ec
->vm_stack
+ th
->ec
->vm_stack_size
- cont
->saved_vm_stack
.clen
,
1327 cont
->saved_vm_stack
.ptr
+ cont
->saved_vm_stack
.slen
,
1328 VALUE
, cont
->saved_vm_stack
.clen
);
1330 MEMCPY(th
->ec
->vm_stack
, cont
->saved_vm_stack
.ptr
, VALUE
, sec
->vm_stack_size
);
1332 /* other members of ec */
1334 th
->ec
->cfp
= sec
->cfp
;
1335 th
->ec
->raised_flag
= sec
->raised_flag
;
1336 th
->ec
->tag
= sec
->tag
;
1337 th
->ec
->root_lep
= sec
->root_lep
;
1338 th
->ec
->root_svar
= sec
->root_svar
;
1339 th
->ec
->ensure_list
= sec
->ensure_list
;
1340 th
->ec
->errinfo
= sec
->errinfo
;
1342 VM_ASSERT(th
->ec
->vm_stack
!= NULL
);
1346 fiber_restore_thread(th
, (rb_fiber_t
*)cont
);
1350 NOINLINE(static void fiber_setcontext(rb_fiber_t
*new_fiber
, rb_fiber_t
*old_fiber
));
1353 fiber_setcontext(rb_fiber_t
*new_fiber
, rb_fiber_t
*old_fiber
)
1355 rb_thread_t
*th
= GET_THREAD();
1357 /* save old_fiber's machine stack - to ensure efficient garbage collection */
1358 if (!FIBER_TERMINATED_P(old_fiber
)) {
1359 STACK_GROW_DIR_DETECTION
;
1360 SET_MACHINE_STACK_END(&th
->ec
->machine
.stack_end
);
1361 if (STACK_DIR_UPPER(0, 1)) {
1362 old_fiber
->cont
.machine
.stack_size
= th
->ec
->machine
.stack_start
- th
->ec
->machine
.stack_end
;
1363 old_fiber
->cont
.machine
.stack
= th
->ec
->machine
.stack_end
;
1366 old_fiber
->cont
.machine
.stack_size
= th
->ec
->machine
.stack_end
- th
->ec
->machine
.stack_start
;
1367 old_fiber
->cont
.machine
.stack
= th
->ec
->machine
.stack_start
;
1371 /* exchange machine_stack_start between old_fiber and new_fiber */
1372 old_fiber
->cont
.saved_ec
.machine
.stack_start
= th
->ec
->machine
.stack_start
;
1374 /* old_fiber->machine.stack_end should be NULL */
1375 old_fiber
->cont
.saved_ec
.machine
.stack_end
= NULL
;
1377 // if (DEBUG) fprintf(stderr, "fiber_setcontext: %p[%p] -> %p[%p]\n", (void*)old_fiber, old_fiber->stack.base, (void*)new_fiber, new_fiber->stack.base);
1379 /* swap machine context */
1380 struct coroutine_context
* from
= coroutine_transfer(&old_fiber
->context
, &new_fiber
->context
);
1383 rb_syserr_fail(errno
, "coroutine_transfer");
1386 /* restore thread context */
1387 fiber_restore_thread(th
, old_fiber
);
1389 // It's possible to get here, and new_fiber is already freed.
1390 // if (DEBUG) fprintf(stderr, "fiber_setcontext: %p[%p] <- %p[%p]\n", (void*)old_fiber, old_fiber->stack.base, (void*)new_fiber, new_fiber->stack.base);
1393 NOINLINE(NORETURN(static void cont_restore_1(rb_context_t
*)));
1396 cont_restore_1(rb_context_t
*cont
)
1398 cont_restore_thread(cont
);
1400 /* restore machine stack */
1403 /* workaround for x64 SEH */
1406 _JUMP_BUFFER
*bp
= (void*)&cont
->jmpbuf
;
1407 bp
->Frame
= ((_JUMP_BUFFER
*)((void*)&buf
))->Frame
;
1410 if (cont
->machine
.stack_src
) {
1411 FLUSH_REGISTER_WINDOWS
;
1412 MEMCPY(cont
->machine
.stack_src
, cont
->machine
.stack
,
1413 VALUE
, cont
->machine
.stack_size
);
1416 ruby_longjmp(cont
->jmpbuf
, 1);
1419 NORETURN(NOINLINE(static void cont_restore_0(rb_context_t
*, VALUE
*)));
1422 cont_restore_0(rb_context_t
*cont
, VALUE
*addr_in_prev_frame
)
1424 if (cont
->machine
.stack_src
) {
1426 #define STACK_PAD_SIZE 1
1428 #define STACK_PAD_SIZE 1024
1430 VALUE space
[STACK_PAD_SIZE
];
1432 #if !STACK_GROW_DIRECTION
1433 if (addr_in_prev_frame
> &space
[0]) {
1434 /* Stack grows downward */
1436 #if STACK_GROW_DIRECTION <= 0
1437 volatile VALUE
*const end
= cont
->machine
.stack_src
;
1438 if (&space
[0] > end
) {
1440 volatile VALUE
*sp
= ALLOCA_N(VALUE
, &space
[0] - end
);
1443 cont_restore_0(cont
, &space
[0]);
1447 #if !STACK_GROW_DIRECTION
1450 /* Stack grows upward */
1452 #if STACK_GROW_DIRECTION >= 0
1453 volatile VALUE
*const end
= cont
->machine
.stack_src
+ cont
->machine
.stack_size
;
1454 if (&space
[STACK_PAD_SIZE
] < end
) {
1456 volatile VALUE
*sp
= ALLOCA_N(VALUE
, end
- &space
[STACK_PAD_SIZE
]);
1459 cont_restore_0(cont
, &space
[STACK_PAD_SIZE
-1]);
1463 #if !STACK_GROW_DIRECTION
1467 cont_restore_1(cont
);
1471 * Document-class: Continuation
1473 * Continuation objects are generated by Kernel#callcc,
1474 * after having +require+d <i>continuation</i>. They hold
1475 * a return address and execution context, allowing a nonlocal return
1476 * to the end of the #callcc block from anywhere within a
1477 * program. Continuations are somewhat analogous to a structured
1478 * version of C's <code>setjmp/longjmp</code> (although they contain
1479 * more state, so you might consider them closer to threads).
1483 * require "continuation"
1484 * arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ]
1485 * callcc{|cc| $cc = cc}
1486 * puts(message = arr.shift)
1487 * $cc.call unless message =~ /Max/
1489 * <em>produces:</em>
1496 * Also you can call callcc in other methods:
1498 * require "continuation"
1501 * arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ]
1502 * cc = callcc { |cc| cc }
1504 * return cc, arr.size
1509 * c.call(c) if size > 1
1514 * This (somewhat contrived) example allows the inner loop to abandon
1517 * require "continuation"
1521 * for j in i*5...(i+1)*5
1522 * cont.call() if j == 17
1529 * <em>produces:</em>
1539 * callcc {|cont| block } -> obj
1541 * Generates a Continuation object, which it passes to
1542 * the associated block. You need to <code>require
1543 * 'continuation'</code> before using this method. Performing a
1544 * <em>cont</em><code>.call</code> will cause the #callcc
1545 * to return (as will falling through the end of the block). The
1546 * value returned by the #callcc is the value of the
1547 * block, or the value passed to <em>cont</em><code>.call</code>. See
1548 * class Continuation for more details. Also see
1549 * Kernel#throw for an alternative mechanism for
1550 * unwinding a call stack.
1554 rb_callcc(VALUE self
)
1556 volatile int called
;
1557 volatile VALUE val
= cont_capture(&called
);
1563 return rb_yield(val
);
1568 make_passing_arg(int argc
, const VALUE
*argv
)
1578 return rb_ary_new4(argc
, argv
);
1582 typedef VALUE
e_proc(VALUE
);
1584 /* CAUTION!! : Currently, error in rollback_func is not supported */
1585 /* same as rb_protect if set rollback_func to NULL */
1587 ruby_register_rollback_func_for_ensure(e_proc
*ensure_func
, e_proc
*rollback_func
)
1589 st_table
**table_p
= &GET_VM()->ensure_rollback_table
;
1590 if (UNLIKELY(*table_p
== NULL
)) {
1591 *table_p
= st_init_numtable();
1593 st_insert(*table_p
, (st_data_t
)ensure_func
, (st_data_t
)rollback_func
);
1596 static inline e_proc
*
1597 lookup_rollback_func(e_proc
*ensure_func
)
1599 st_table
*table
= GET_VM()->ensure_rollback_table
;
1601 if (table
&& st_lookup(table
, (st_data_t
)ensure_func
, &val
))
1602 return (e_proc
*) val
;
1603 return (e_proc
*) Qundef
;
1608 rollback_ensure_stack(VALUE self
,rb_ensure_list_t
*current
,rb_ensure_entry_t
*target
)
1610 rb_ensure_list_t
*p
;
1611 rb_ensure_entry_t
*entry
;
1619 for (p
=current
; p
; p
=p
->next
)
1622 for (entry
=target
; entry
->marker
; entry
++)
1625 /* search common stack point */
1627 base_point
= cur_size
;
1628 while (base_point
) {
1629 if (target_size
>= base_point
&&
1630 p
->entry
.marker
== target
[target_size
- base_point
].marker
)
1636 /* rollback function check */
1637 for (i
=0; i
< target_size
- base_point
; i
++) {
1638 if (!lookup_rollback_func(target
[i
].e_proc
)) {
1639 rb_raise(rb_eRuntimeError
, "continuation called from out of critical rb_ensure scope");
1642 /* pop ensure stack */
1643 while (cur_size
> base_point
) {
1644 /* escape from ensure block */
1645 (*current
->entry
.e_proc
)(current
->entry
.data2
);
1646 current
= current
->next
;
1649 /* push ensure stack */
1650 for (j
= 0; j
< i
; j
++) {
1651 func
= lookup_rollback_func(target
[i
- j
- 1].e_proc
);
1652 if ((VALUE
)func
!= Qundef
) {
1653 (*func
)(target
[i
- j
- 1].data2
);
1658 NORETURN(static VALUE
rb_cont_call(int argc
, VALUE
*argv
, VALUE contval
));
1662 * cont.call(args, ...)
1665 * Invokes the continuation. The program continues from the end of
1666 * the #callcc block. If no arguments are given, the original #callcc
1667 * returns +nil+. If one argument is given, #callcc returns
1668 * it. Otherwise, an array containing <i>args</i> is returned.
1670 * callcc {|cont| cont.call } #=> nil
1671 * callcc {|cont| cont.call 1 } #=> 1
1672 * callcc {|cont| cont.call 1, 2, 3 } #=> [1, 2, 3]
1676 rb_cont_call(int argc
, VALUE
*argv
, VALUE contval
)
1678 rb_context_t
*cont
= cont_ptr(contval
);
1679 rb_thread_t
*th
= GET_THREAD();
1681 if (cont_thread_value(cont
) != th
->self
) {
1682 rb_raise(rb_eRuntimeError
, "continuation called across threads");
1684 if (cont
->saved_ec
.fiber_ptr
) {
1685 if (th
->ec
->fiber_ptr
!= cont
->saved_ec
.fiber_ptr
) {
1686 rb_raise(rb_eRuntimeError
, "continuation called across fiber");
1689 rollback_ensure_stack(contval
, th
->ec
->ensure_list
, cont
->ensure_array
);
1692 cont
->value
= make_passing_arg(argc
, argv
);
1694 cont_restore_0(cont
, &contval
);
1695 UNREACHABLE_RETURN(Qnil
);
1703 * Document-class: Fiber
1705 * Fibers are primitives for implementing light weight cooperative
1706 * concurrency in Ruby. Basically they are a means of creating code blocks
1707 * that can be paused and resumed, much like threads. The main difference
1708 * is that they are never preempted and that the scheduling must be done by
1709 * the programmer and not the VM.
1711 * As opposed to other stackless light weight concurrency models, each fiber
1712 * comes with a stack. This enables the fiber to be paused from deeply
1713 * nested function calls within the fiber block. See the ruby(1)
1714 * manpage to configure the size of the fiber stack(s).
1716 * When a fiber is created it will not run automatically. Rather it must
1717 * be explicitly asked to run using the Fiber#resume method.
1718 * The code running inside the fiber can give up control by calling
1719 * Fiber.yield in which case it yields control back to caller (the
1720 * caller of the Fiber#resume).
1722 * Upon yielding or termination the Fiber returns the value of the last
1723 * executed expression
1727 * fiber = Fiber.new do
1740 * FiberError: dead fiber called
1742 * The Fiber#resume method accepts an arbitrary number of parameters,
1743 * if it is the first call to #resume then they will be passed as
1744 * block arguments. Otherwise they will be the return value of the
1745 * call to Fiber.yield
1749 * fiber = Fiber.new do |first|
1750 * second = Fiber.yield first + 2
1753 * puts fiber.resume 10
1754 * puts fiber.resume 1_000_000
1755 * puts fiber.resume "The fiber will be dead before I can cause trouble"
1761 * FiberError: dead fiber called
1763 * == Non-blocking Fibers
1765 * The concept of <em>non-blocking fiber</em> was introduced in Ruby 3.0.
1766 * A non-blocking fiber, when reaching a operation that would normally block
1767 * the fiber (like <code>sleep</code>, or wait for another process or I/O)
1768 * will yield control to other fibers and allow the <em>scheduler</em> to
1769 * handle blocking and waking up (resuming) this fiber when it can proceed.
1771 * For a Fiber to behave as non-blocking, it need to be created in Fiber.new with
1772 * <tt>blocking: false</tt> (which is the default), and Fiber.scheduler
1773 * should be set with Fiber.set_scheduler. If Fiber.scheduler is not set in
1774 * the current thread, blocking and non-blocking fibers' behavior is identical.
1776 * Ruby doesn't provide a scheduler class: it is expected to be implemented by
1777 * the user and correspond to Fiber::SchedulerInterface.
1779 * There is also Fiber.schedule method, which is expected to immediately perform
1780 * the given block in a non-blocking manner. Its actual implementation is up to
1785 static const rb_data_type_t fiber_data_type
= {
1787 {fiber_mark
, fiber_free
, fiber_memsize
, fiber_compact
,},
1788 0, 0, RUBY_TYPED_FREE_IMMEDIATELY
1792 fiber_alloc(VALUE klass
)
1794 return TypedData_Wrap_Struct(klass
, &fiber_data_type
, 0);
1798 fiber_t_alloc(VALUE fiber_value
, unsigned int blocking
)
1801 rb_thread_t
*th
= GET_THREAD();
1803 if (DATA_PTR(fiber_value
) != 0) {
1804 rb_raise(rb_eRuntimeError
, "cannot initialize twice");
1807 THREAD_MUST_BE_RUNNING(th
);
1808 fiber
= ZALLOC(rb_fiber_t
);
1809 fiber
->cont
.self
= fiber_value
;
1810 fiber
->cont
.type
= FIBER_CONTEXT
;
1811 fiber
->blocking
= blocking
;
1812 cont_init(&fiber
->cont
, th
);
1814 fiber
->cont
.saved_ec
.fiber_ptr
= fiber
;
1815 rb_ec_clear_vm_stack(&fiber
->cont
.saved_ec
);
1819 /* fiber->status == 0 == CREATED
1820 * So that we don't need to set status: fiber_status_set(fiber, FIBER_CREATED); */
1821 VM_ASSERT(FIBER_CREATED_P(fiber
));
1823 DATA_PTR(fiber_value
) = fiber
;
1829 fiber_initialize(VALUE self
, VALUE proc
, struct fiber_pool
* fiber_pool
, unsigned int blocking
)
1831 rb_fiber_t
*fiber
= fiber_t_alloc(self
, blocking
);
1833 fiber
->first_proc
= proc
;
1834 fiber
->stack
.base
= NULL
;
1835 fiber
->stack
.pool
= fiber_pool
;
1841 fiber_prepare_stack(rb_fiber_t
*fiber
)
1843 rb_context_t
*cont
= &fiber
->cont
;
1844 rb_execution_context_t
*sec
= &cont
->saved_ec
;
1846 size_t vm_stack_size
= 0;
1847 VALUE
*vm_stack
= fiber_initialize_coroutine(fiber
, &vm_stack_size
);
1849 /* initialize cont */
1850 cont
->saved_vm_stack
.ptr
= NULL
;
1851 rb_ec_initialize_vm_stack(sec
, vm_stack
, vm_stack_size
/ sizeof(VALUE
));
1854 sec
->local_storage
= NULL
;
1855 sec
->local_storage_recursive_hash
= Qnil
;
1856 sec
->local_storage_recursive_hash_for_trace
= Qnil
;
1859 static struct fiber_pool
*
1860 rb_fiber_pool_default(VALUE pool
)
1862 return &shared_fiber_pool
;
1867 rb_fiber_initialize_kw(int argc
, VALUE
* argv
, VALUE self
, int kw_splat
)
1870 VALUE blocking
= Qfalse
;
1872 if (kw_splat
!= RB_NO_KEYWORDS
) {
1873 VALUE options
= Qnil
;
1874 VALUE arguments
[2] = {Qundef
};
1876 argc
= rb_scan_args_kw(kw_splat
, argc
, argv
, ":", &options
);
1877 rb_get_kwargs(options
, fiber_initialize_keywords
, 0, 2, arguments
);
1879 if (arguments
[0] != Qundef
) {
1880 blocking
= arguments
[0];
1883 if (arguments
[1] != Qundef
) {
1884 pool
= arguments
[1];
1888 return fiber_initialize(self
, rb_block_proc(), rb_fiber_pool_default(pool
), RTEST(blocking
));
1893 * Fiber.new(blocking: false) { |*args| ... } -> fiber
1895 * Creates new Fiber. Initially, the fiber is not running and can be resumed with
1896 * #resume. Arguments to the first #resume call will be passed to the block:
1898 * f = Fiber.new do |initial|
1901 * puts "current: #{current.inspect}"
1902 * current = Fiber.yield
1905 * f.resume(100) # prints: current: 100
1906 * f.resume(1, 2, 3) # prints: current: [1, 2, 3]
1907 * f.resume # prints: current: nil
1908 * # ... and so on ...
1910 * If <tt>blocking: false</tt> is passed to <tt>Fiber.new</tt>, _and_ current thread
1911 * has a Fiber.scheduler defined, the Fiber becomes non-blocking (see "Non-blocking
1912 * Fibers" section in class docs).
1915 rb_fiber_initialize(int argc
, VALUE
* argv
, VALUE self
)
1917 return rb_fiber_initialize_kw(argc
, argv
, self
, rb_keyword_given_p());
1921 rb_fiber_new(rb_block_call_func_t func
, VALUE obj
)
1923 return fiber_initialize(fiber_alloc(rb_cFiber
), rb_proc_new(func
, obj
), rb_fiber_pool_default(Qnil
), 1);
1927 rb_fiber_s_schedule_kw(int argc
, VALUE
* argv
, int kw_splat
)
1929 rb_thread_t
* th
= GET_THREAD();
1930 VALUE scheduler
= th
->scheduler
;
1933 if (scheduler
!= Qnil
) {
1934 fiber
= rb_funcall_passing_block_kw(scheduler
, rb_intern("fiber"), argc
, argv
, kw_splat
);
1937 rb_raise(rb_eRuntimeError
, "No scheduler is available!");
1945 * Fiber.schedule { |*args| ... } -> fiber
1947 * The method is <em>expected</em> to immediately run the provided block of code in a
1948 * separate non-blocking fiber.
1950 * puts "Go to sleep!"
1952 * Fiber.set_scheduler(MyScheduler.new)
1955 * puts "Going to sleep"
1957 * puts "I slept well"
1960 * puts "Wakey-wakey, sleepyhead"
1962 * Assuming MyScheduler is properly implemented, this program will produce:
1966 * Wakey-wakey, sleepyhead
1967 * ...1 sec pause here...
1970 * ...e.g. on the first blocking operation inside the Fiber (<tt>sleep(1)</tt>),
1971 * the control is yielded to the outside code (main fiber), and <em>at the end
1972 * of that execution</em>, the scheduler takes care of properly resuming all the
1975 * Note that the behavior described above is how the method is <em>expected</em>
1976 * to behave, actual behavior is up to the current scheduler's implementation of
1977 * Fiber::SchedulerInterface#fiber method. Ruby doesn't enforce this method to
1978 * behave in any particular way.
1980 * If the scheduler is not set, the method raises
1981 * <tt>RuntimeError (No scheduler is available!)</tt>.
1985 rb_fiber_s_schedule(int argc
, VALUE
*argv
, VALUE obj
)
1987 return rb_fiber_s_schedule_kw(argc
, argv
, rb_keyword_given_p());
1992 * Fiber.scheduler -> obj or nil
1994 * Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler.
1995 * Returns +nil+ if no scheduler is set (which is the default), and non-blocking fibers'
1996 # behavior is the same as blocking.
1997 * (see "Non-blocking fibers" section in class docs for details about the scheduler concept).
2001 rb_fiber_s_scheduler(VALUE klass
)
2003 return rb_fiber_scheduler_get();
2008 * Fiber.current_scheduler -> obj or nil
2010 * Returns the Fiber scheduler, that was last set for the current thread with Fiber.set_scheduler
2011 * if and only if the current fiber is non-blocking.
2015 rb_fiber_current_scheduler(VALUE klass
)
2017 return rb_fiber_scheduler_current();
2022 * Fiber.set_scheduler(scheduler) -> scheduler
2024 * Sets the Fiber scheduler for the current thread. If the scheduler is set, non-blocking
2025 * fibers (created by Fiber.new with <tt>blocking: false</tt>, or by Fiber.schedule)
2026 * call that scheduler's hook methods on potentially blocking operations, and the current
2027 * thread will call scheduler's +close+ method on finalization (allowing the scheduler to
2028 * properly manage all non-finished fibers).
2030 * +scheduler+ can be an object of any class corresponding to Fiber::SchedulerInterface. Its
2031 * implementation is up to the user.
2033 * See also the "Non-blocking fibers" section in class docs.
2037 rb_fiber_set_scheduler(VALUE klass
, VALUE scheduler
)
2039 return rb_fiber_scheduler_set(scheduler
);
2042 static void rb_fiber_terminate(rb_fiber_t
*fiber
, int need_interrupt
, VALUE err
);
2045 rb_fiber_start(rb_fiber_t
*fiber
)
2047 rb_thread_t
* volatile th
= fiber
->cont
.saved_ec
.thread_ptr
;
2050 enum ruby_tag_type state
;
2051 int need_interrupt
= TRUE
;
2053 VM_ASSERT(th
->ec
== GET_EC());
2054 VM_ASSERT(FIBER_RESUMED_P(fiber
));
2056 if (fiber
->blocking
) {
2060 EC_PUSH_TAG(th
->ec
);
2061 if ((state
= EC_EXEC_TAG()) == TAG_NONE
) {
2062 rb_context_t
*cont
= &VAR_FROM_MEMORY(fiber
)->cont
;
2064 const VALUE
*argv
, args
= cont
->value
;
2065 GetProcPtr(fiber
->first_proc
, proc
);
2066 argv
= (argc
= cont
->argc
) > 1 ? RARRAY_CONST_PTR(args
) : &args
;
2068 th
->ec
->errinfo
= Qnil
;
2069 th
->ec
->root_lep
= rb_vm_proc_local_ep(fiber
->first_proc
);
2070 th
->ec
->root_svar
= Qfalse
;
2072 EXEC_EVENT_HOOK(th
->ec
, RUBY_EVENT_FIBER_SWITCH
, th
->self
, 0, 0, 0, Qnil
);
2073 cont
->value
= rb_vm_invoke_proc(th
->ec
, proc
, argc
, argv
, cont
->kw_splat
, VM_BLOCK_HANDLER_NONE
);
2079 err
= th
->ec
->errinfo
;
2080 VM_ASSERT(FIBER_RESUMED_P(fiber
));
2082 if (state
== TAG_RAISE
) {
2085 else if (state
== TAG_FATAL
) {
2086 rb_threadptr_pending_interrupt_enque(th
, err
);
2089 err
= rb_vm_make_jump_tag_but_local_jump(state
, err
);
2091 need_interrupt
= TRUE
;
2094 rb_fiber_terminate(fiber
, need_interrupt
, err
);
2098 root_fiber_alloc(rb_thread_t
*th
)
2100 VALUE fiber_value
= fiber_alloc(rb_cFiber
);
2101 rb_fiber_t
*fiber
= th
->ec
->fiber_ptr
;
2103 VM_ASSERT(DATA_PTR(fiber_value
) == NULL
);
2104 VM_ASSERT(fiber
->cont
.type
== FIBER_CONTEXT
);
2105 VM_ASSERT(fiber
->status
== FIBER_RESUMED
);
2107 th
->root_fiber
= fiber
;
2108 DATA_PTR(fiber_value
) = fiber
;
2109 fiber
->cont
.self
= fiber_value
;
2111 coroutine_initialize_main(&fiber
->context
);
2117 rb_threadptr_root_fiber_setup(rb_thread_t
*th
)
2119 rb_fiber_t
*fiber
= ruby_mimmalloc(sizeof(rb_fiber_t
));
2121 rb_bug("%s", strerror(errno
)); /* ... is it possible to call rb_bug here? */
2123 MEMZERO(fiber
, rb_fiber_t
, 1);
2124 fiber
->cont
.type
= FIBER_CONTEXT
;
2125 fiber
->cont
.saved_ec
.fiber_ptr
= fiber
;
2126 fiber
->cont
.saved_ec
.thread_ptr
= th
;
2127 fiber
->blocking
= 1;
2128 fiber_status_set(fiber
, FIBER_RESUMED
); /* skip CREATED */
2129 th
->ec
= &fiber
->cont
.saved_ec
;
2130 // This skips mjit_cont_new for the initial thread because mjit_enabled is always false
2131 // at this point. mjit_init calls rb_fiber_init_mjit_cont again for this root_fiber.
2132 rb_fiber_init_mjit_cont(fiber
);
2136 rb_threadptr_root_fiber_release(rb_thread_t
*th
)
2138 if (th
->root_fiber
) {
2139 /* ignore. A root fiber object will free th->ec */
2142 rb_execution_context_t
*ec
= GET_EC();
2144 VM_ASSERT(th
->ec
->fiber_ptr
->cont
.type
== FIBER_CONTEXT
);
2145 VM_ASSERT(th
->ec
->fiber_ptr
->cont
.self
== 0);
2148 rb_ractor_set_current_ec(th
->ractor
, NULL
);
2150 fiber_free(th
->ec
->fiber_ptr
);
2156 rb_threadptr_root_fiber_terminate(rb_thread_t
*th
)
2158 rb_fiber_t
*fiber
= th
->ec
->fiber_ptr
;
2160 fiber
->status
= FIBER_TERMINATED
;
2162 // The vm_stack is `alloca`ed on the thread stack, so it's gone too:
2163 rb_ec_clear_vm_stack(th
->ec
);
2166 static inline rb_fiber_t
*
2169 rb_execution_context_t
*ec
= GET_EC();
2170 if (ec
->fiber_ptr
->cont
.self
== 0) {
2171 root_fiber_alloc(rb_ec_thread_ptr(ec
));
2173 return ec
->fiber_ptr
;
2176 static inline rb_fiber_t
*
2177 return_fiber(bool terminate
)
2179 rb_fiber_t
*fiber
= fiber_current();
2180 rb_fiber_t
*prev
= fiber
->prev
;
2184 prev
->resuming_fiber
= NULL
;
2189 rb_raise(rb_eFiberError
, "attempt to yield on a not resumed fiber");
2192 rb_thread_t
*th
= GET_THREAD();
2193 rb_fiber_t
*root_fiber
= th
->root_fiber
;
2195 VM_ASSERT(root_fiber
!= NULL
);
2197 // search resuming fiber
2198 for (fiber
= root_fiber
; fiber
->resuming_fiber
; fiber
= fiber
->resuming_fiber
) {
2206 rb_fiber_current(void)
2208 return fiber_current()->cont
.self
;
2211 // Prepare to execute next_fiber on the given thread.
2213 fiber_store(rb_fiber_t
*next_fiber
, rb_thread_t
*th
)
2217 if (th
->ec
->fiber_ptr
!= NULL
) {
2218 fiber
= th
->ec
->fiber_ptr
;
2221 /* create root fiber */
2222 fiber
= root_fiber_alloc(th
);
2225 if (FIBER_CREATED_P(next_fiber
)) {
2226 fiber_prepare_stack(next_fiber
);
2229 VM_ASSERT(FIBER_RESUMED_P(fiber
) || FIBER_TERMINATED_P(fiber
));
2230 VM_ASSERT(FIBER_RUNNABLE_P(next_fiber
));
2232 if (FIBER_RESUMED_P(fiber
)) fiber_status_set(fiber
, FIBER_SUSPENDED
);
2234 fiber_status_set(next_fiber
, FIBER_RESUMED
);
2235 fiber_setcontext(next_fiber
, fiber
);
2239 fiber_switch(rb_fiber_t
*fiber
, int argc
, const VALUE
*argv
, int kw_splat
, rb_fiber_t
*resuming_fiber
, bool yielding
)
2242 rb_context_t
*cont
= &fiber
->cont
;
2243 rb_thread_t
*th
= GET_THREAD();
2245 /* make sure the root_fiber object is available */
2246 if (th
->root_fiber
== NULL
) root_fiber_alloc(th
);
2248 if (th
->ec
->fiber_ptr
== fiber
) {
2249 /* ignore fiber context switch
2250 * because destination fiber is the same as current fiber
2252 return make_passing_arg(argc
, argv
);
2255 if (cont_thread_value(cont
) != th
->self
) {
2256 rb_raise(rb_eFiberError
, "fiber called across threads");
2259 if (FIBER_TERMINATED_P(fiber
)) {
2260 value
= rb_exc_new2(rb_eFiberError
, "dead fiber called");
2262 if (!FIBER_TERMINATED_P(th
->ec
->fiber_ptr
)) {
2263 rb_exc_raise(value
);
2264 VM_UNREACHABLE(fiber_switch
);
2267 /* th->ec->fiber_ptr is also dead => switch to root fiber */
2268 /* (this means we're being called from rb_fiber_terminate, */
2269 /* and the terminated fiber's return_fiber() is already dead) */
2270 VM_ASSERT(FIBER_SUSPENDED_P(th
->root_fiber
));
2272 cont
= &th
->root_fiber
->cont
;
2274 cont
->value
= value
;
2276 fiber_setcontext(th
->root_fiber
, th
->ec
->fiber_ptr
);
2278 VM_UNREACHABLE(fiber_switch
);
2282 VM_ASSERT(FIBER_RUNNABLE_P(fiber
));
2284 rb_fiber_t
*current_fiber
= fiber_current();
2286 VM_ASSERT(!current_fiber
->resuming_fiber
);
2288 if (resuming_fiber
) {
2289 current_fiber
->resuming_fiber
= resuming_fiber
;
2290 fiber
->prev
= fiber_current();
2291 fiber
->yielding
= 0;
2294 VM_ASSERT(!current_fiber
->yielding
);
2296 current_fiber
->yielding
= 1;
2299 if (current_fiber
->blocking
) {
2304 cont
->kw_splat
= kw_splat
;
2305 cont
->value
= make_passing_arg(argc
, argv
);
2307 fiber_store(fiber
, th
);
2309 // We cannot free the stack until the pthread is joined:
2310 #ifndef COROUTINE_PTHREAD_CONTEXT
2311 if (resuming_fiber
&& FIBER_TERMINATED_P(fiber
)) {
2312 fiber_stack_release(fiber
);
2316 if (fiber_current()->blocking
) {
2320 RUBY_VM_CHECK_INTS(th
->ec
);
2322 EXEC_EVENT_HOOK(th
->ec
, RUBY_EVENT_FIBER_SWITCH
, th
->self
, 0, 0, 0, Qnil
);
2324 current_fiber
= th
->ec
->fiber_ptr
;
2325 value
= current_fiber
->cont
.value
;
2326 if (current_fiber
->cont
.argc
== -1) rb_exc_raise(value
);
2331 rb_fiber_transfer(VALUE fiber_value
, int argc
, const VALUE
*argv
)
2333 return fiber_switch(fiber_ptr(fiber_value
), argc
, argv
, RB_NO_KEYWORDS
, NULL
, false);
2338 * fiber.blocking? -> true or false
2340 * Returns +true+ if +fiber+ is blocking and +false+ otherwise.
2341 * Fiber is non-blocking if it was created via passing <tt>blocking: false</tt>
2342 * to Fiber.new, or via Fiber.schedule.
2344 * Note that, even if the method returns +false+, the fiber behaves differently
2345 * only if Fiber.scheduler is set in the current thread.
2347 * See the "Non-blocking fibers" section in class docs for details.
2351 rb_fiber_blocking_p(VALUE fiber
)
2353 return RBOOL(fiber_ptr(fiber
)->blocking
!= 0);
2358 * Fiber.blocking? -> false or 1
2360 * Returns +false+ if the current fiber is non-blocking.
2361 * Fiber is non-blocking if it was created via passing <tt>blocking: false</tt>
2362 * to Fiber.new, or via Fiber.schedule.
2364 * If the current Fiber is blocking, the method returns 1.
2365 * Future developments may allow for situations where larger integers
2366 * could be returned.
2368 * Note that, even if the method returns +false+, Fiber behaves differently
2369 * only if Fiber.scheduler is set in the current thread.
2371 * See the "Non-blocking fibers" section in class docs for details.
2375 rb_fiber_s_blocking_p(VALUE klass
)
2377 rb_thread_t
*thread
= GET_THREAD();
2378 unsigned blocking
= thread
->blocking
;
2383 return INT2NUM(blocking
);
2387 rb_fiber_close(rb_fiber_t
*fiber
)
2389 fiber_status_set(fiber
, FIBER_TERMINATED
);
2393 rb_fiber_terminate(rb_fiber_t
*fiber
, int need_interrupt
, VALUE error
)
2395 VALUE value
= fiber
->cont
.value
;
2397 VM_ASSERT(FIBER_RESUMED_P(fiber
));
2398 rb_fiber_close(fiber
);
2400 fiber
->cont
.machine
.stack
= NULL
;
2401 fiber
->cont
.machine
.stack_size
= 0;
2403 rb_fiber_t
*next_fiber
= return_fiber(true);
2405 if (need_interrupt
) RUBY_VM_SET_INTERRUPT(&next_fiber
->cont
.saved_ec
);
2408 fiber_switch(next_fiber
, -1, &error
, RB_NO_KEYWORDS
, NULL
, false);
2410 fiber_switch(next_fiber
, 1, &value
, RB_NO_KEYWORDS
, NULL
, false);
2414 fiber_resume_kw(rb_fiber_t
*fiber
, int argc
, const VALUE
*argv
, int kw_splat
)
2416 rb_fiber_t
*current_fiber
= fiber_current();
2418 if (argc
== -1 && FIBER_CREATED_P(fiber
)) {
2419 rb_raise(rb_eFiberError
, "cannot raise exception on unborn fiber");
2421 else if (FIBER_TERMINATED_P(fiber
)) {
2422 rb_raise(rb_eFiberError
, "attempt to resume a terminated fiber");
2424 else if (fiber
== current_fiber
) {
2425 rb_raise(rb_eFiberError
, "attempt to resume the current fiber");
2427 else if (fiber
->prev
!= NULL
) {
2428 rb_raise(rb_eFiberError
, "attempt to resume a resumed fiber (double resume)");
2430 else if (fiber
->resuming_fiber
) {
2431 rb_raise(rb_eFiberError
, "attempt to resume a resuming fiber");
2433 else if (fiber
->prev
== NULL
&&
2434 (!fiber
->yielding
&& fiber
->status
!= FIBER_CREATED
)) {
2435 rb_raise(rb_eFiberError
, "attempt to resume a transferring fiber");
2438 VALUE result
= fiber_switch(fiber
, argc
, argv
, kw_splat
, fiber
, false);
2444 rb_fiber_resume_kw(VALUE self
, int argc
, const VALUE
*argv
, int kw_splat
)
2446 return fiber_resume_kw(fiber_ptr(self
), argc
, argv
, kw_splat
);
2450 rb_fiber_resume(VALUE self
, int argc
, const VALUE
*argv
)
2452 return fiber_resume_kw(fiber_ptr(self
), argc
, argv
, RB_NO_KEYWORDS
);
2456 rb_fiber_yield_kw(int argc
, const VALUE
*argv
, int kw_splat
)
2458 return fiber_switch(return_fiber(false), argc
, argv
, kw_splat
, NULL
, true);
2462 rb_fiber_yield(int argc
, const VALUE
*argv
)
2464 return fiber_switch(return_fiber(false), argc
, argv
, RB_NO_KEYWORDS
, NULL
, true);
2468 rb_fiber_reset_root_local_storage(rb_thread_t
*th
)
2470 if (th
->root_fiber
&& th
->root_fiber
!= th
->ec
->fiber_ptr
) {
2471 th
->ec
->local_storage
= th
->root_fiber
->cont
.saved_ec
.local_storage
;
2477 * fiber.alive? -> true or false
2479 * Returns true if the fiber can still be resumed (or transferred
2480 * to). After finishing execution of the fiber block this method will
2481 * always return +false+.
2484 rb_fiber_alive_p(VALUE fiber_value
)
2486 return FIBER_TERMINATED_P(fiber_ptr(fiber_value
)) ? Qfalse
: Qtrue
;
2491 * fiber.resume(args, ...) -> obj
2493 * Resumes the fiber from the point at which the last Fiber.yield was
2494 * called, or starts running it if it is the first call to
2495 * #resume. Arguments passed to resume will be the value of the
2496 * Fiber.yield expression or will be passed as block parameters to
2497 * the fiber's block if this is the first #resume.
2499 * Alternatively, when resume is called it evaluates to the arguments passed
2500 * to the next Fiber.yield statement inside the fiber's block
2501 * or to the block value if it runs to completion without any
2505 rb_fiber_m_resume(int argc
, VALUE
*argv
, VALUE fiber
)
2507 return rb_fiber_resume_kw(fiber
, argc
, argv
, rb_keyword_given_p());
2512 * fiber.backtrace -> array
2513 * fiber.backtrace(start) -> array
2514 * fiber.backtrace(start, count) -> array
2515 * fiber.backtrace(start..end) -> array
2517 * Returns the current execution stack of the fiber. +start+, +count+ and +end+ allow
2518 * to select only parts of the backtrace.
2532 * f = Fiber.new { level1 }
2534 * # It is empty before the fiber started
2541 * #=> ["test.rb:2:in `yield'", "test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'", "test.rb:13:in `block in <main>'"]
2542 * p f.backtrace(1) # start from the item 1
2543 * #=> ["test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'", "test.rb:13:in `block in <main>'"]
2544 * p f.backtrace(2, 2) # start from item 2, take 2
2545 * #=> ["test.rb:6:in `level2'", "test.rb:10:in `level1'"]
2546 * p f.backtrace(1..3) # take items from 1 to 3
2547 * #=> ["test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'"]
2551 * # It is nil after the fiber is finished
2557 rb_fiber_backtrace(int argc
, VALUE
*argv
, VALUE fiber
)
2559 return rb_vm_backtrace(argc
, argv
, &fiber_ptr(fiber
)->cont
.saved_ec
);
2564 * fiber.backtrace_locations -> array
2565 * fiber.backtrace_locations(start) -> array
2566 * fiber.backtrace_locations(start, count) -> array
2567 * fiber.backtrace_locations(start..end) -> array
2569 * Like #backtrace, but returns each line of the execution stack as a
2570 * Thread::Backtrace::Location. Accepts the same arguments as #backtrace.
2572 * f = Fiber.new { Fiber.yield }
2574 * loc = f.backtrace_locations.first
2575 * loc.label #=> "yield"
2576 * loc.path #=> "test.rb"
2582 rb_fiber_backtrace_locations(int argc
, VALUE
*argv
, VALUE fiber
)
2584 return rb_vm_backtrace_locations(argc
, argv
, &fiber_ptr(fiber
)->cont
.saved_ec
);
2589 * fiber.transfer(args, ...) -> obj
2591 * Transfer control to another fiber, resuming it from where it last
2592 * stopped or starting it if it was not resumed before. The calling
2593 * fiber will be suspended much like in a call to
2596 * The fiber which receives the transfer call treats it much like
2597 * a resume call. Arguments passed to transfer are treated like those
2600 * The two style of control passing to and from fiber (one is #resume and
2601 * Fiber::yield, another is #transfer to and from fiber) can't be freely
2604 * * If the Fiber's lifecycle had started with transfer, it will never
2605 * be able to yield or be resumed control passing, only
2606 * finish or transfer back. (It still can resume other fibers that
2607 * are allowed to be resumed.)
2608 * * If the Fiber's lifecycle had started with resume, it can yield
2609 * or transfer to another Fiber, but can receive control back only
2610 * the way compatible with the way it was given away: if it had
2611 * transferred, it only can be transferred back, and if it had
2612 * yielded, it only can be resumed back. After that, it again can
2613 * transfer or yield.
2615 * If those rules are broken FiberError is raised.
2617 * For an individual Fiber design, yield/resume is easier to use
2618 * (the Fiber just gives away control, it doesn't need to think
2619 * about who the control is given to), while transfer is more flexible
2620 * for complex cases, allowing to build arbitrary graphs of Fibers
2621 * dependent on each other.
2626 * manager = nil # For local var to be visible inside worker block
2628 * # This fiber would be started with transfer
2629 * # It can't yield, and can't be resumed
2630 * worker = Fiber.new { |work|
2631 * puts "Worker: starts"
2632 * puts "Worker: Performed #{work.inspect}, transferring back"
2633 * # Fiber.yield # this would raise FiberError: attempt to yield on a not resumed fiber
2634 * # manager.resume # this would raise FiberError: attempt to resume a resumed fiber (double resume)
2635 * manager.transfer(work.capitalize)
2638 * # This fiber would be started with resume
2639 * # It can yield or transfer, and can be transferred
2641 * manager = Fiber.new {
2642 * puts "Manager: starts"
2643 * puts "Manager: transferring 'something' to worker"
2644 * result = worker.transfer('something')
2645 * puts "Manager: worker returned #{result.inspect}"
2646 * # worker.resume # this would raise FiberError: attempt to resume a transferring fiber
2647 * Fiber.yield # this is OK, the fiber transferred from and to, now it can yield
2648 * puts "Manager: finished"
2651 * puts "Starting the manager"
2653 * puts "Resuming the manager"
2654 * # manager.transfer # this would raise FiberError: attempt to transfer to a yielding fiber
2659 * Starting the manager
2661 * Manager: transferring 'something' to worker
2663 * Worker: Performed "something", transferring back
2664 * Manager: worker returned "Something"
2665 * Resuming the manager
2670 rb_fiber_m_transfer(int argc
, VALUE
*argv
, VALUE self
)
2672 return rb_fiber_transfer_kw(self
, argc
, argv
, rb_keyword_given_p());
2676 fiber_transfer_kw(rb_fiber_t
*fiber
, int argc
, const VALUE
*argv
, int kw_splat
)
2678 if (fiber
->resuming_fiber
) {
2679 rb_raise(rb_eFiberError
, "attempt to transfer to a resuming fiber");
2682 if (fiber
->yielding
) {
2683 rb_raise(rb_eFiberError
, "attempt to transfer to a yielding fiber");
2686 return fiber_switch(fiber
, argc
, argv
, kw_splat
, NULL
, false);
2690 rb_fiber_transfer_kw(VALUE self
, int argc
, const VALUE
*argv
, int kw_splat
)
2692 return fiber_transfer_kw(fiber_ptr(self
), argc
, argv
, kw_splat
);
2697 * Fiber.yield(args, ...) -> obj
2699 * Yields control back to the context that resumed the fiber, passing
2700 * along any arguments that were passed to it. The fiber will resume
2701 * processing at this point when #resume is called next.
2702 * Any arguments passed to the next #resume will be the value that
2703 * this Fiber.yield expression evaluates to.
2706 rb_fiber_s_yield(int argc
, VALUE
*argv
, VALUE klass
)
2708 return rb_fiber_yield_kw(argc
, argv
, rb_keyword_given_p());
2712 fiber_raise(rb_fiber_t
*fiber
, int argc
, const VALUE
*argv
)
2714 VALUE exception
= rb_make_exception(argc
, argv
);
2716 if (fiber
->resuming_fiber
) {
2717 rb_raise(rb_eFiberError
, "attempt to raise a resuming fiber");
2719 else if (FIBER_SUSPENDED_P(fiber
) && !fiber
->yielding
) {
2720 return fiber_transfer_kw(fiber
, -1, &exception
, RB_NO_KEYWORDS
);
2723 return fiber_resume_kw(fiber
, -1, &exception
, RB_NO_KEYWORDS
);
2728 rb_fiber_raise(VALUE fiber
, int argc
, const VALUE
*argv
)
2730 return fiber_raise(fiber_ptr(fiber
), argc
, argv
);
2735 * fiber.raise -> obj
2736 * fiber.raise(string) -> obj
2737 * fiber.raise(exception [, string [, array]]) -> obj
2739 * Raises an exception in the fiber at the point at which the last
2740 * +Fiber.yield+ was called. If the fiber has not been started or has
2741 * already run to completion, raises +FiberError+. If the fiber is
2742 * yielding, it is resumed. If it is transferring, it is transferred into.
2743 * But if it is resuming, raises +FiberError+.
2745 * With no arguments, raises a +RuntimeError+. With a single +String+
2746 * argument, raises a +RuntimeError+ with the string as a message. Otherwise,
2747 * the first parameter should be the name of an +Exception+ class (or an
2748 * object that returns an +Exception+ object when sent an +exception+
2749 * message). The optional second parameter sets the message associated with
2750 * the exception, and the third parameter is an array of callback information.
2751 * Exceptions are caught by the +rescue+ clause of <code>begin...end</code>
2755 rb_fiber_m_raise(int argc
, VALUE
*argv
, VALUE self
)
2757 return rb_fiber_raise(self
, argc
, argv
);
2762 * Fiber.current -> fiber
2764 * Returns the current fiber. If you are not running in the context of
2765 * a fiber this method will return the root fiber.
2768 rb_fiber_s_current(VALUE klass
)
2770 return rb_fiber_current();
2774 fiber_to_s(VALUE fiber_value
)
2776 const rb_fiber_t
*fiber
= fiber_ptr(fiber_value
);
2777 const rb_proc_t
*proc
;
2778 char status_info
[0x20];
2780 if (fiber
->resuming_fiber
) {
2781 snprintf(status_info
, 0x20, " (%s by resuming)", fiber_status_name(fiber
->status
));
2784 snprintf(status_info
, 0x20, " (%s)", fiber_status_name(fiber
->status
));
2787 if (!rb_obj_is_proc(fiber
->first_proc
)) {
2788 VALUE str
= rb_any_to_s(fiber_value
);
2789 strlcat(status_info
, ">", sizeof(status_info
));
2790 rb_str_set_len(str
, RSTRING_LEN(str
)-1);
2791 rb_str_cat_cstr(str
, status_info
);
2794 GetProcPtr(fiber
->first_proc
, proc
);
2795 return rb_block_to_s(fiber_value
, &proc
->block
, status_info
);
2798 #ifdef HAVE_WORKING_FORK
2800 rb_fiber_atfork(rb_thread_t
*th
)
2802 if (th
->root_fiber
) {
2803 if (&th
->root_fiber
->cont
.saved_ec
!= th
->ec
) {
2804 th
->root_fiber
= th
->ec
->fiber_ptr
;
2806 th
->root_fiber
->prev
= 0;
2811 #ifdef RB_EXPERIMENTAL_FIBER_POOL
2813 fiber_pool_free(void *ptr
)
2815 struct fiber_pool
* fiber_pool
= ptr
;
2816 RUBY_FREE_ENTER("fiber_pool");
2818 fiber_pool_free_allocations(fiber_pool
->allocations
);
2819 ruby_xfree(fiber_pool
);
2821 RUBY_FREE_LEAVE("fiber_pool");
2825 fiber_pool_memsize(const void *ptr
)
2827 const struct fiber_pool
* fiber_pool
= ptr
;
2828 size_t size
= sizeof(*fiber_pool
);
2830 size
+= fiber_pool
->count
* fiber_pool
->size
;
2835 static const rb_data_type_t FiberPoolDataType
= {
2837 {NULL
, fiber_pool_free
, fiber_pool_memsize
,},
2838 0, 0, RUBY_TYPED_FREE_IMMEDIATELY
2842 fiber_pool_alloc(VALUE klass
)
2844 struct fiber_pool
* fiber_pool
= RB_ALLOC(struct fiber_pool
);
2846 return TypedData_Wrap_Struct(klass
, &FiberPoolDataType
, fiber_pool
);
2850 rb_fiber_pool_initialize(int argc
, VALUE
* argv
, VALUE self
)
2852 rb_thread_t
*th
= GET_THREAD();
2853 VALUE size
= Qnil
, count
= Qnil
, vm_stack_size
= Qnil
;
2854 struct fiber_pool
* fiber_pool
= NULL
;
2856 // Maybe these should be keyword arguments.
2857 rb_scan_args(argc
, argv
, "03", &size
, &count
, &vm_stack_size
);
2860 size
= INT2NUM(th
->vm
->default_params
.fiber_machine_stack_size
);
2864 count
= INT2NUM(128);
2867 if (NIL_P(vm_stack_size
)) {
2868 vm_stack_size
= INT2NUM(th
->vm
->default_params
.fiber_vm_stack_size
);
2871 TypedData_Get_Struct(self
, struct fiber_pool
, &FiberPoolDataType
, fiber_pool
);
2873 fiber_pool_initialize(fiber_pool
, NUM2SIZET(size
), NUM2SIZET(count
), NUM2SIZET(vm_stack_size
));
2880 * Document-class: FiberError
2882 * Raised when an invalid operation is attempted on a Fiber, in
2883 * particular when attempting to call/resume a dead fiber,
2884 * attempting to yield from the root fiber, or calling a fiber across
2887 * fiber = Fiber.new{}
2888 * fiber.resume #=> nil
2889 * fiber.resume #=> FiberError: dead fiber called
2893 * Document-class: Fiber::SchedulerInterface
2895 * This is not an existing class, but documentation of the interface that Scheduler
2896 * object should comply to in order to be used as argument to Fiber.scheduler and handle non-blocking
2897 * fibers. See also the "Non-blocking fibers" section in Fiber class docs for explanations
2900 * Scheduler's behavior and usage are expected to be as follows:
2902 * * When the execution in the non-blocking Fiber reaches some blocking operation (like
2903 * sleep, wait for a process, or a non-ready I/O), it calls some of the scheduler's
2904 * hook methods, listed below.
2905 * * Scheduler somehow registers what the current fiber is waiting on, and yields control
2906 * to other fibers with Fiber.yield (so the fiber would be suspended while expecting its
2907 * wait to end, and other fibers in the same thread can perform)
2908 * * At the end of the current thread execution, the scheduler's method #close is called
2909 * * The scheduler runs into a wait loop, checking all the blocked fibers (which it has
2910 * registered on hook calls) and resuming them when the awaited resource is ready
2911 * (e.g. I/O ready or sleep time elapsed).
2913 * A typical implementation would probably rely for this closing loop on a gem like
2914 * EventMachine[https://github.com/eventmachine/eventmachine] or
2915 * Async[https://github.com/socketry/async].
2917 * This way concurrent execution will be achieved transparently for every
2918 * individual Fiber's code.
2922 * * #io_wait, #io_read, and #io_write
2926 * * #address_resolve
2927 * * #block and #unblock
2928 * * (the list is expanded as Ruby developers make more methods having non-blocking calls)
2930 * When not specified otherwise, the hook implementations are mandatory: if they are not
2931 * implemented, the methods trying to call hook will fail. To provide backward compatibility,
2932 * in the future hooks will be optional (if they are not implemented, due to the scheduler
2933 * being created for the older Ruby version, the code which needs this hook will not fail,
2934 * and will just behave in a blocking fashion).
2936 * It is also strongly recommended that the scheduler implements the #fiber method, which is
2937 * delegated to by Fiber.schedule.
2939 * Sample _toy_ implementation of the scheduler can be found in Ruby's code, in
2940 * <tt>test/fiber/scheduler.rb</tt>
2944 #if 0 /* for RDoc */
2947 * Document-method: Fiber::SchedulerInterface#close
2949 * Called when the current thread exits. The scheduler is expected to implement this
2950 * method in order to allow all waiting fibers to finalize their execution.
2952 * The suggested pattern is to implement the main event loop in the #close method.
2956 rb_fiber_scheduler_interface_close(VALUE self
)
2961 * Document-method: SchedulerInterface#process_wait
2962 * call-seq: process_wait(pid, flags)
2964 * Invoked by Process::Status.wait in order to wait for a specified process.
2965 * See that method description for arguments description.
2967 * Suggested minimal implementation:
2970 * Process::Status.wait(pid, flags)
2973 * This hook is optional: if it is not present in the current scheduler,
2974 * Process::Status.wait will behave as a blocking method.
2976 * Expected to return a Process::Status instance.
2979 rb_fiber_scheduler_interface_process_wait(VALUE self
)
2984 * Document-method: SchedulerInterface#io_wait
2985 * call-seq: io_wait(io, events, timeout)
2987 * Invoked by IO#wait, IO#wait_readable, IO#wait_writable to ask whether the
2988 * specified descriptor is ready for specified events within
2989 * the specified +timeout+.
2991 * +events+ is a bit mask of <tt>IO::READABLE</tt>, <tt>IO::WRITABLE</tt>, and
2992 * <tt>IO::PRIORITY</tt>.
2994 * Suggested implementation should register which Fiber is waiting for which
2995 * resources and immediately calling Fiber.yield to pass control to other
2996 * fibers. Then, in the #close method, the scheduler might dispatch all the
2997 * I/O resources to fibers waiting for it.
2999 * Expected to return the subset of events that are ready immediately.
3003 rb_fiber_scheduler_interface_io_wait(VALUE self
)
3008 * Document-method: SchedulerInterface#io_read
3009 * call-seq: io_read(io, buffer, length) -> read length or -errno
3011 * Invoked by IO#read to read +length+ bytes from +io+ into a specified
3012 * +buffer+ (see IO::Buffer).
3014 * The +length+ argument is the "minimum length to be read".
3015 * If the IO buffer size is 8KiB, but the +length+ is +1024+ (1KiB), up to
3016 * 8KiB might be read, but at least 1KiB will be.
3017 * Generally, the only case where less data than +length+ will be read is if
3018 * there is an error reading the data.
3020 * Specifying a +length+ of 0 is valid and means try reading at least once
3021 * and return any available data.
3023 * Suggested implementation should try to read from +io+ in a non-blocking
3024 * manner and call #io_wait if the +io+ is not ready (which will yield control
3027 * See IO::Buffer for an interface available to return data.
3029 * Expected to return number of bytes read, or, in case of an error, <tt>-errno</tt>
3030 * (negated number corresponding to system's error code).
3032 * The method should be considered _experimental_.
3035 rb_fiber_scheduler_interface_io_read(VALUE self
)
3040 * Document-method: SchedulerInterface#io_write
3041 * call-seq: io_write(io, buffer, length) -> written length or -errno
3043 * Invoked by IO#write to write +length+ bytes to +io+ from
3044 * from a specified +buffer+ (see IO::Buffer).
3046 * The +length+ argument is the "(minimum) length to be written".
3047 * If the IO buffer size is 8KiB, but the +length+ specified is 1024 (1KiB),
3048 * at most 8KiB will be written, but at least 1KiB will be.
3049 * Generally, the only case where less data than +length+ will be written is if
3050 * there is an error writing the data.
3052 * Specifying a +length+ of 0 is valid and means try writing at least once,
3053 * as much data as possible.
3055 * Suggested implementation should try to write to +io+ in a non-blocking
3056 * manner and call #io_wait if the +io+ is not ready (which will yield control
3059 * See IO::Buffer for an interface available to get data from buffer efficiently.
3061 * Expected to return number of bytes written, or, in case of an error, <tt>-errno</tt>
3062 * (negated number corresponding to system's error code).
3064 * The method should be considered _experimental_.
3067 rb_fiber_scheduler_interface_io_write(VALUE self
)
3072 * Document-method: SchedulerInterface#kernel_sleep
3073 * call-seq: kernel_sleep(duration = nil)
3075 * Invoked by Kernel#sleep and Mutex#sleep and is expected to provide
3076 * an implementation of sleeping in a non-blocking way. Implementation might
3077 * register the current fiber in some list of "which fiber wait until what
3078 * moment", call Fiber.yield to pass control, and then in #close resume
3079 * the fibers whose wait period has elapsed.
3083 rb_fiber_scheduler_interface_kernel_sleep(VALUE self
)
3088 * Document-method: SchedulerInterface#address_resolve
3089 * call-seq: address_resolve(hostname) -> array_of_strings or nil
3091 * Invoked by any method that performs a non-reverse DNS lookup. The most
3092 * notable method is Addrinfo.getaddrinfo, but there are many other.
3094 * The method is expected to return an array of strings corresponding to ip
3095 * addresses the +hostname+ is resolved to, or +nil+ if it can not be resolved.
3097 * Fairly exhaustive list of all possible call-sites:
3099 * - Addrinfo.getaddrinfo
3104 * - Addrinfo.marshal_load
3108 * - IPSocket.getaddress
3109 * - TCPSocket.gethostbyname
3110 * - UDPSocket#connect
3113 * - Socket.getaddrinfo
3114 * - Socket.gethostbyname
3115 * - Socket.pack_sockaddr_in
3116 * - Socket.sockaddr_in
3117 * - Socket.unpack_sockaddr_in
3120 rb_fiber_scheduler_interface_address_resolve(VALUE self
)
3125 * Document-method: SchedulerInterface#timeout_after
3126 * call-seq: timeout_after(duration, exception_class, *exception_arguments, &block) -> result of block
3128 * Invoked by Timeout.timeout to execute the given +block+ within the given
3129 * +duration+. It can also be invoked directly by the scheduler or user code.
3131 * Attempt to limit the execution time of a given +block+ to the given
3132 * +duration+ if possible. When a non-blocking operation causes the +block+'s
3133 * execution time to exceed the specified +duration+, that non-blocking
3134 * operation should be interrupted by raising the specified +exception_class+
3135 * constructed with the given +exception_arguments+.
3137 * General execution timeouts are often considered risky. This implementation
3138 * will only interrupt non-blocking operations. This is by design because it's
3139 * expected that non-blocking operations can fail for a variety of
3140 * unpredictable reasons, so applications should already be robust in handling
3141 * these conditions and by implication timeouts.
3143 * However, as a result of this design, if the +block+ does not invoke any
3144 * non-blocking operations, it will be impossible to interrupt it. If you
3145 * desire to provide predictable points for timeouts, consider adding
3148 * If the block is executed successfully, its result will be returned.
3150 * The exception will typically be raised using Fiber#raise.
3153 rb_fiber_scheduler_interface_timeout_after(VALUE self
)
3158 * Document-method: SchedulerInterface#block
3159 * call-seq: block(blocker, timeout = nil)
3161 * Invoked by methods like Thread.join, and by Mutex, to signify that current
3162 * Fiber is blocked until further notice (e.g. #unblock) or until +timeout+ has
3165 * +blocker+ is what we are waiting on, informational only (for debugging and
3166 * logging). There are no guarantee about its value.
3168 * Expected to return boolean, specifying whether the blocking operation was
3169 * successful or not.
3172 rb_fiber_scheduler_interface_block(VALUE self
)
3177 * Document-method: SchedulerInterface#unblock
3178 * call-seq: unblock(blocker, fiber)
3180 * Invoked to wake up Fiber previously blocked with #block (for example, Mutex#lock
3181 * calls #block and Mutex#unlock calls #unblock). The scheduler should use
3182 * the +fiber+ parameter to understand which fiber is unblocked.
3184 * +blocker+ is what was awaited for, but it is informational only (for debugging
3185 * and logging), and it is not guaranteed to be the same value as the +blocker+ for
3190 rb_fiber_scheduler_interface_unblock(VALUE self
)
3195 * Document-method: SchedulerInterface#fiber
3196 * call-seq: fiber(&block)
3198 * Implementation of the Fiber.schedule. The method is <em>expected</em> to immediately
3199 * run the given block of code in a separate non-blocking fiber, and to return that Fiber.
3201 * Minimal suggested implementation is:
3204 * fiber = Fiber.new(blocking: false, &block)
3210 rb_fiber_scheduler_interface_fiber(VALUE self
)
3218 rb_thread_t
*th
= GET_THREAD();
3219 size_t vm_stack_size
= th
->vm
->default_params
.fiber_vm_stack_size
;
3220 size_t machine_stack_size
= th
->vm
->default_params
.fiber_machine_stack_size
;
3221 size_t stack_size
= machine_stack_size
+ vm_stack_size
;
3225 GetSystemInfo(&info
);
3226 pagesize
= info
.dwPageSize
;
3227 #else /* not WIN32 */
3228 pagesize
= sysconf(_SC_PAGESIZE
);
3230 SET_MACHINE_STACK_END(&th
->ec
->machine
.stack_end
);
3232 fiber_pool_initialize(&shared_fiber_pool
, stack_size
, FIBER_POOL_INITIAL_SIZE
, vm_stack_size
);
3234 fiber_initialize_keywords
[0] = rb_intern_const("blocking");
3235 fiber_initialize_keywords
[1] = rb_intern_const("pool");
3237 const char *fiber_shared_fiber_pool_free_stacks
= getenv("RUBY_SHARED_FIBER_POOL_FREE_STACKS");
3238 if (fiber_shared_fiber_pool_free_stacks
) {
3239 shared_fiber_pool
.free_stacks
= atoi(fiber_shared_fiber_pool_free_stacks
);
3242 rb_cFiber
= rb_define_class("Fiber", rb_cObject
);
3243 rb_define_alloc_func(rb_cFiber
, fiber_alloc
);
3244 rb_eFiberError
= rb_define_class("FiberError", rb_eStandardError
);
3245 rb_define_singleton_method(rb_cFiber
, "yield", rb_fiber_s_yield
, -1);
3246 rb_define_singleton_method(rb_cFiber
, "current", rb_fiber_s_current
, 0);
3247 rb_define_method(rb_cFiber
, "initialize", rb_fiber_initialize
, -1);
3248 rb_define_method(rb_cFiber
, "blocking?", rb_fiber_blocking_p
, 0);
3249 rb_define_method(rb_cFiber
, "resume", rb_fiber_m_resume
, -1);
3250 rb_define_method(rb_cFiber
, "raise", rb_fiber_m_raise
, -1);
3251 rb_define_method(rb_cFiber
, "backtrace", rb_fiber_backtrace
, -1);
3252 rb_define_method(rb_cFiber
, "backtrace_locations", rb_fiber_backtrace_locations
, -1);
3253 rb_define_method(rb_cFiber
, "to_s", fiber_to_s
, 0);
3254 rb_define_alias(rb_cFiber
, "inspect", "to_s");
3255 rb_define_method(rb_cFiber
, "transfer", rb_fiber_m_transfer
, -1);
3256 rb_define_method(rb_cFiber
, "alive?", rb_fiber_alive_p
, 0);
3258 rb_define_singleton_method(rb_cFiber
, "blocking?", rb_fiber_s_blocking_p
, 0);
3259 rb_define_singleton_method(rb_cFiber
, "scheduler", rb_fiber_s_scheduler
, 0);
3260 rb_define_singleton_method(rb_cFiber
, "set_scheduler", rb_fiber_set_scheduler
, 1);
3261 rb_define_singleton_method(rb_cFiber
, "current_scheduler", rb_fiber_current_scheduler
, 0);
3263 rb_define_singleton_method(rb_cFiber
, "schedule", rb_fiber_s_schedule
, -1);
3265 #if 0 /* for RDoc */
3266 rb_cFiberScheduler
= rb_define_class_under(rb_cFiber
, "SchedulerInterface", rb_cObject
);
3267 rb_define_method(rb_cFiberScheduler
, "close", rb_fiber_scheduler_interface_close
, 0);
3268 rb_define_method(rb_cFiberScheduler
, "process_wait", rb_fiber_scheduler_interface_process_wait
, 0);
3269 rb_define_method(rb_cFiberScheduler
, "io_wait", rb_fiber_scheduler_interface_io_wait
, 0);
3270 rb_define_method(rb_cFiberScheduler
, "io_read", rb_fiber_scheduler_interface_io_read
, 0);
3271 rb_define_method(rb_cFiberScheduler
, "io_write", rb_fiber_scheduler_interface_io_write
, 0);
3272 rb_define_method(rb_cFiberScheduler
, "kernel_sleep", rb_fiber_scheduler_interface_kernel_sleep
, 0);
3273 rb_define_method(rb_cFiberScheduler
, "address_resolve", rb_fiber_scheduler_interface_address_resolve
, 0);
3274 rb_define_method(rb_cFiberScheduler
, "timeout_after", rb_fiber_scheduler_interface_timeout_after
, 0);
3275 rb_define_method(rb_cFiberScheduler
, "block", rb_fiber_scheduler_interface_block
, 0);
3276 rb_define_method(rb_cFiberScheduler
, "unblock", rb_fiber_scheduler_interface_unblock
, 0);
3277 rb_define_method(rb_cFiberScheduler
, "fiber", rb_fiber_scheduler_interface_fiber
, 0);
3280 #ifdef RB_EXPERIMENTAL_FIBER_POOL
3281 rb_cFiberPool
= rb_define_class("Pool", rb_cFiber
);
3282 rb_define_alloc_func(rb_cFiberPool
, fiber_pool_alloc
);
3283 rb_define_method(rb_cFiberPool
, "initialize", rb_fiber_pool_initialize
, -1);
3286 rb_provide("fiber.so");
3289 RUBY_SYMBOL_EXPORT_BEGIN
3292 ruby_Init_Continuation_body(void)
3294 rb_cContinuation
= rb_define_class("Continuation", rb_cObject
);
3295 rb_undef_alloc_func(rb_cContinuation
);
3296 rb_undef_method(CLASS_OF(rb_cContinuation
), "new");
3297 rb_define_method(rb_cContinuation
, "call", rb_cont_call
, -1);
3298 rb_define_method(rb_cContinuation
, "[]", rb_cont_call
, -1);
3299 rb_define_global_function("callcc", rb_callcc
, 0);
3302 RUBY_SYMBOL_EXPORT_END