класс Fiber

VALUE
rb_fiber_alive_p(VALUE fiber_value)
{
    return RBOOL(!FIBER_TERMINATED_P(fiber_ptr(fiber_value)));
}

Возвращает true, если волокно всё ещё может быть возобновлено (или передано). После завершения выполнения блока волокна этот метод всегда будет возвращать false.

static VALUE
rb_fiber_backtrace(int argc, VALUE *argv, VALUE fiber)
{
    return rb_vm_backtrace(argc, argv, &fiber_ptr(fiber)->cont.saved_ec);
}

Возвращает текущий стек выполнения волокна. start, count и end позволяют выбрать только части трассировки.

def level3
  Fiber.yield
end

def level2
  level3
end

def level1
  level2
end

f = Fiber.new { level1 }

# It is empty before the fiber started
f.backtrace
#=> []

f.resume

f.backtrace
#=> ["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>'"]
p f.backtrace(1) # start from the item 1
#=> ["test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'", "test.rb:13:in `block in <main>'"]
p f.backtrace(2, 2) # start from item 2, take 2
#=> ["test.rb:6:in `level2'", "test.rb:10:in `level1'"]
p f.backtrace(1..3) # take items from 1 to 3
#=> ["test.rb:2:in `level3'", "test.rb:6:in `level2'", "test.rb:10:in `level1'"]

f.resume

# It is nil after the fiber is finished
f.backtrace
#=> nil

static VALUE
rb_fiber_backtrace_locations(int argc, VALUE *argv, VALUE fiber)
{
    return rb_vm_backtrace_locations(argc, argv, &fiber_ptr(fiber)->cont.saved_ec);
}

Как backtrace, но возвращает каждую строку стека выполнения как Thread::Backtrace::Location. Принимает те же аргументы, что и backtrace.

f = Fiber.new { Fiber.yield }
f.resume
loc = f.backtrace_locations.first
loc.label  #=> "yield"
loc.path   #=> "test.rb"
loc.lineno #=> 1

VALUE
rb_fiber_blocking_p(VALUE fiber)
{
    return RBOOL(fiber_ptr(fiber)->blocking);
}

Возвращает true, если fiber блокируется и false в противном случае. Fiber не блокируется, если он был создан путем передачи blocking: false в Fiber.new или через Fiber.schedule.

Обратите внимание, что даже если метод возвращает false, волокно ведет себя по-разному только в том случае, если Fiber.scheduler установлен в текущем потоке.

См. раздел «Неблокирующие волокна» в документации класса для получения подробной информации.

static VALUE
rb_fiber_m_kill(VALUE self)
{
    rb_fiber_t *fiber = fiber_ptr(self);

    if (fiber->killed) return Qfalse;
    fiber->killed = 1;

    if (fiber->status == FIBER_CREATED) {
        fiber->status = FIBER_TERMINATED;
    }
    else if (fiber->status != FIBER_TERMINATED) {
        if (fiber_current() == fiber) {
            fiber_check_killed(fiber);
        }
        else {
            fiber_raise(fiber_ptr(self), Qnil);
        }
    }

    return self;
}

Завершает волокно, вызывая неперехватываемое исключение. Оно завершает только данное волокно, а не другое волокно, возвращая nil другому волокну, если это волокно вызывало resume или transfer.

Fiber#kill прерывает другое волокно только тогда, когда оно находится в Fiber.yield. При вызове в текущем волокне оно вызывает это исключение в месте вызова Fiber#kill.

Если волокно не было запущено, переходит непосредственно в завершенное состояние.

Если волокно уже завершено, ничего не делает.

Вызывает FiberError, если вызывается для волокна, принадлежащего другому потоку.

static VALUE
rb_fiber_m_raise(int argc, VALUE *argv, VALUE self)
{
    return rb_fiber_raise(self, argc, argv);
}

Вызывает исключение в волокне в точке, в которой был вызван последний Fiber.yield. Если волокно не было запущено или уже выполнено до конца, вызывает FiberError. Если волокно приостановлено, оно возобновляется. Если оно переносится, оно переносится внутрь. Но если оно возобновляется, вызывает FiberError.

Без аргументов вызывает RuntimeError. С одним аргументом String вызывает RuntimeError со строкой в качестве сообщения. В противном случае первый параметр должен быть именем класса Exception (или объекта, который возвращает объект Exception при отправке сообщения exception). Необязательный второй параметр устанавливает сообщение, связанное с исключением, а третий параметр — это массив информации о вызове. Исключения перехватываются предложением rescue блоков begin...end.

Вызывает FiberError, если вызывается для Fiber, принадлежащего другому Thread.

См. Kernel#raise для получения дополнительной информации.

static VALUE
rb_fiber_m_resume(int argc, VALUE *argv, VALUE fiber)
{
    return rb_fiber_resume_kw(fiber, argc, argv, rb_keyword_given_p());
}

Возобновляет волокно с точки, в которой был вызван последний Fiber.yield, или начинает его выполнение, если это первый вызов resume. Аргументы, переданные в resume, будут значением выражения Fiber.yield или будут переданы в качестве параметров блока в блок волокна, если это первый resume.

В качестве альтернативы, когда вызывается resume, он вычисляется в аргументы, переданные в следующее выражение Fiber.yield внутри блока волокна, или в значение блока, если он выполняется до завершения без какого-либо Fiber.yield

static VALUE
rb_fiber_storage_get(VALUE self)
{
    storage_access_must_be_from_same_fiber(self);

    VALUE storage = fiber_storage_get(fiber_ptr(self), FALSE);

    if (storage == Qnil) {
        return Qnil;
    }
    else {
        return rb_obj_dup(storage);
    }
}

Возвращает копию хэш-таблицы хранилища для волокна. Метод может быть вызван только для Fiber.current.

static VALUE
rb_fiber_storage_set(VALUE self, VALUE value)
{
    if (rb_warning_category_enabled_p(RB_WARN_CATEGORY_EXPERIMENTAL)) {
        rb_category_warn(RB_WARN_CATEGORY_EXPERIMENTAL,
          "Fiber#storage= is experimental and may be removed in the future!");
    }

    storage_access_must_be_from_same_fiber(self);
    fiber_storage_validate(value);

    fiber_ptr(self)->cont.saved_ec.storage = rb_obj_dup(value);
    return value;
}

Устанавливает хэш-таблицу хранилища для волокна. Эта функция экспериментальная и может измениться в будущем. Метод может быть вызван только для Fiber.current.

Следует осторожно использовать этот метод, так как вы можете непреднамеренно очистить важное состояние хранилища волокна. В основном следует предпочесть назначение конкретных ключей в хранилище с помощью Fiber::[]=.

Вы также можете использовать Fiber.new(storage: nil) для создания волокна с пустым хранилищем.

Пример:

while request = request_queue.pop
  # Reset the per-request state:
  Fiber.current.storage = nil
  handle_request(request)
end

static VALUE
rb_fiber_m_transfer(int argc, VALUE *argv, VALUE self)
{
    return rb_fiber_transfer_kw(self, argc, argv, rb_keyword_given_p());
}

Передать управление другой волокне, возобновив его с точки остановки или запустив, если оно раньше не возобновлялось. Вызывающее волокно будет приостановлено так же, как при вызове Fiber.yield.

Волокно, которое получает вызов transfer, обрабатывает его как вызов resume. Аргументы, переданные в transfer, обрабатываются так же, как те, которые передаются в resume.

Два способа передачи управления волокну (один — resume и Fiber::yield, другой — transfer к волокну и от него) не могут быть свободно смешаны.

• Если жизненный цикл волокна начался с transfer, оно никогда не сможет уступить или быть возобновлено, только завершиться или передать управление обратно. (При этом оно всё ещё может возобновить другие волокна, которые разрешено возобновлять.)

• Если жизненный цикл волокна начался с resume, оно может уступить или передать управление другому Fiber, но может получить управление обратно только так, как оно было отдано: если оно передавало управление, то его можно только передать обратно, а если оно уступило, то его можно только возобновить. После этого оно снова может передавать или уступать управление.

Если эти правила нарушены, возбуждается FiberError.

Для индивидуального дизайна Fiber, yield/resume проще в использовании (волокно просто отдает управление, ему не нужно думать, кому оно отдаётся), в то время как transfer более гибкий для сложных случаев, позволяя строить произвольные графики зависимых друг от друга волокон.

Пример:

manager = nil # For local var to be visible inside worker block

# This fiber would be started with transfer
# It can't yield, and can't be resumed
worker = Fiber.new { |work|
  puts "Worker: starts"
  puts "Worker: Performed #{work.inspect}, transferring back"
  # Fiber.yield     # this would raise FiberError: attempt to yield on a not resumed fiber
  # manager.resume  # this would raise FiberError: attempt to resume a resumed fiber (double resume)
  manager.transfer(work.capitalize)
}

# This fiber would be started with resume
# It can yield or transfer, and can be transferred
# back or resumed
manager = Fiber.new {
  puts "Manager: starts"
  puts "Manager: transferring 'something' to worker"
  result = worker.transfer('something')
  puts "Manager: worker returned #{result.inspect}"
  # worker.resume    # this would raise FiberError: attempt to resume a transferring fiber
  Fiber.yield        # this is OK, the fiber transferred from and to, now it can yield
  puts "Manager: finished"
}

puts "Starting the manager"
manager.resume
puts "Resuming the manager"
# manager.transfer  # this would raise FiberError: attempt to transfer to a yielding fiber
manager.resume

приводит к

Starting the manager
Manager: starts
Manager: transferring 'something' to worker
Worker: starts
Worker: Performed "something", transferring back
Manager: worker returned "Something"
Resuming the manager
Manager: finished