класс 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.

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.

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

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

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

Если эти правила нарушены, генерируется FiberError.

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

Пример:

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