класс Fiber

Возвращает значение переменной хранилища волокна, идентифицируемой с помощью key.

key должен быть символом, а значение задаётся с помощью Fiber#[]= или Fiber#storage.

См. также Fiber::[]=.

Присваивает value переменной хранилища волокна, идентифицируемой с помощью key. Если переменная не существует, она создаётся.

key должен быть Symbol, иначе будет вызвано исключение TypeError.

См. также Fiber::[].

Принудительно переводит волокно в блокирующий режим на время выполнения блока. Возвращает результат выполнения блока.

Подробности см. в разделе «Неблокирующие волокна» документации класса.

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

Если текущее Fiber является блокирующим, метод возвращает 1. В будущем метод может возвращать и бо́льшие целые числа.

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

Подробности см. в разделе «Неблокирующие волокна» документации класса.

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

Возвращает планировщик Fiber, последний раз заданный для текущего потока с помощью Fiber.set_scheduler, только если текущее волокно является неблокирующим.

Создаёт новое Fiber. Изначально волокно не запущено, его можно возобновить с помощью resume. Аргументы первого вызова resume будут переданы блоку:

f = Fiber.new do |initial|
   current = initial
   loop do
     puts "current: #{current.inspect}"
     current = Fiber.yield
   end
end
f.resume(100)     # prints: current: 100
f.resume(1, 2, 3) # prints: current: [1, 2, 3]
f.resume          # prints: current: nil
# ... and so on ...

Если при вызове Fiber.new передан blocking: false и для текущего потока задан Fiber.scheduler, Fiber становится неблокирующим (см. раздел «Неблокирующие волокна» документации класса).

Если storage не указан, по умолчанию волокно наследует копию хранилища текущего волокна. Это то же самое, что указать storage: true.

Fiber[:x] = 1
Fiber.new do
  Fiber[:x] # => 1
  Fiber[:x] = 2
end.resume
Fiber[:x] # => 1

Если заданный storage — это nil, эта функция отложенно инициализирует внутреннее хранилище, которое изначально представляет собой пустой хеш.

Fiber[:x] = "Hello World"
Fiber.new(storage: nil) do
  Fiber[:x] # nil
end

В противном случае заданный storage используется как хранилище нового волокна и должен быть экземпляром Hash.

Явное использование storage: true в настоящее время является экспериментальным и может измениться в будущем.

Предполагается, что этот метод немедленно запустит предоставленный блок кода в отдельном неблокирующем волокне.

puts "Go to sleep!"

Fiber.set_scheduler(MyScheduler.new)

Fiber.schedule do
  puts "Going to sleep"
  sleep(1)
  puts "I slept well"
end

puts "Wakey-wakey, sleepyhead"

Если MyScheduler реализован должным образом, программа выведет:

Go to sleep!
Going to sleep
Wakey-wakey, sleepyhead
...1 sec pause here...
I slept well

…например, при первой блокирующей операции внутри Fiber (sleep(1)) управление передаётся внешнему коду (главному волокну), а после завершения этого кода планировщик должным образом возобновляет все заблокированные волокна.

Обратите внимание: описанное выше поведение — это то, как метод должен работать; фактическое поведение зависит от реализации метода Fiber::Scheduler#fiber текущим планировщиком. Ruby не требует от этого метода какого-либо определённого поведения.

Если планировщик не задан, метод вызывает исключение RuntimeError (No scheduler is available!).

Возвращает планировщик Fiber, последний раз заданный для текущего потока с помощью Fiber.set_scheduler. Возвращает nil, если планировщик не задан (это значение используется по умолчанию); в таком случае неблокирующие волокна ведут себя так же, как блокирующие. (Подробности о понятии планировщика см. в разделе «Неблокирующие волокна» документации класса.)

Задаёт планировщик Fiber для текущего потока. Если планировщик задан, неблокирующие волокна (созданные с помощью Fiber.new с аргументом blocking: false или с помощью Fiber.schedule) вызывают методы-перехватчики планировщика при потенциально блокирующих операциях, а текущий поток при завершении вызывает метод планировщика close (это позволяет планировщику должным образом управлять всеми незавершёнными волокнами).

scheduler может быть объектом любого класса, соответствующего интерфейсу Fiber::Scheduler. Реализация предоставляется пользователем.

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

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

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

Возвращает текущий стек вызовов волокна. 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

Подобно 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

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

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

Подробности см. в разделе «Неблокирующие волокна» документации класса.

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

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

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

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

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

Вызывает исключение в волокне в точке, где последний раз был вызван Fiber.yield.

f = Fiber.new {
  puts "Before the yield"
  Fiber.yield 1 # -- exception will be raised here
  puts "After the yield"
}

p f.resume
f.raise "Gotcha"

Вывод

Before the first yield
1
t.rb:8:in 'Fiber.yield': Gotcha (RuntimeError)
  from t.rb:8:in 'block in <main>'

Если волокно ещё не запускалось или уже завершило выполнение, возникает исключение FiberError. Если волокно уступает управление, оно возобновляется. Если оно передаёт управление, выполнение переключается на него. Если же оно возобновляется, возникает исключение FiberError.

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

Дополнительные сведения об аргументах см. в описании Kernel#raise.

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

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

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

Задаёт хеш хранилища волокна. Эта возможность является экспериментальной и может измениться в будущем. Метод можно вызывать только для 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

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

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

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

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

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

При нарушении этих правил возникает исключение FiberError.

Для отдельного сценария с Fiber использовать yield/resume проще (волокно Fiber просто уступает управление и ему не нужно знать, кому оно передаётся), тогда как 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