Improve documentation on fibers

[lenkis]

(1) about fiber.testcancel()

Sergey Й, [16 Jul 2019 at 17:18:33]:
fiber.testcancel() - это магическая функция? Ее exception нельзя перехватить?

tarantool> cleanup_ok = false
---
...

tarantool> f = fiber.create(function() while pcall(fiber.testcancel) do fiber.sleep(1)  end cleanup_ok = true end)
---
...

tarantool> f
---
- status: suspended
  name: lua
  id: 120
...

tarantool> f:cancel()
---
...

tarantool>
---
...

tarantool> f
---
- the fiber is dead
...

tarantool> cleanup_ok
---
- false
...

для сравнения

tarantool> err = false f = fiber.create(function() while pcall(function() if err then error() end end) do fiber.sleep(1) end print("\n\ncleanup ok !!!!!!!!!!!!!") end)
---
...

tarantool> err = true
---
...

tarantool>

cleanup ok !!!!!!!!!!!!!

---
...

Где-нибудь в доках есть объяснение?

(2) about fiber_object.cancel()

Sergey Й, [16 Jul 2019 at 17:28:34]:
еще по докам

tarantool> f = fiber.create(fiber.sleep, 999)
---
...

tarantool> f
---
- status: suspended
  name: lua
  id: 145
...

tarantool> f:cancel()
---
...

tarantool> f
---
- the fiber is dead
...

tarantool> f:id()
---
- 145
...

tarantool> box.info.version
---
- 1.10.2-0-gc0d8063b6
...

https://www.tarantool.io/en/doc/1.10/reference/reference_lua/fiber/#lua-function.fiber_object.cancel

After a fiber has been cancelled, attempts to operate on it will cause errors, for example fiber_object:id() will cause error: the fiber is dead.

No, the real behavior is different!

[lenkis]

(1)
Konstantin Osipov, [16 Jul 2019 at 18:04:07]:
fiber_testcancel() бросает fiber is cancelled исключение если файбер cancelнули
но снять состояние cancelled перехватом исключения не получится
так что функция вполне себе обычная, а вот состояние cacncelled - нет
если файбер is cancelled, то лучше всего его завершить как можно скорее, т.к. любой вызов практически проверяет это состояние и возврщает ошибку если cancelled флаг стоит
и мы также рекомендуем писать приложения - если файбер кенсельнули, то код файбера должен по быстрому склеить ласты, даже если это какие-то вычисления

(2)
Konstantin Osipov, [16 Jul 2019 at 18:06:20]:
f:id() переделали и он стал работать с мёртвым файбером, да
доки надо исправить.
но в целом утверждение верно - кроме id, status, join я даже не знаю что ещё будет работать с данным файбером

[izmalk]

@Totktonada is this text ok with you?
Also, if you don't mind - can you please suggest a short example code solution for this aspect (implementation of cancelled fiber testcancel check and ending its execution correctly)?

[Totktonada]

I suggest to pcall the entire function (othside of a loop) and place fiber.testcancel() within the loop. Then perform cleanup actions after the pcall. The change for the example above would look so:

f = fiber.create(function() pcall(function() while true do fiber.sleep(1) fiber.testcancel() end end) cleanup_ok = true end)

The reason why the original code does not perform cleanup_ok = true is that fiber.sleep(1) also checks whether a current fiber was cancelled.

The test is okay. As a reader I would want to know more about 'Most types of calls': is it just about fiber.<...>() calls? Or box functions too? However I cannot provide more details about that, so let consider the wording okay for now.

Nit: 'status checks' means fiber.status()? Or fiber.testcancel()? It is unclear.