Skip to content

Improve documentation on fibers #830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
lenkis opened this issue Jul 16, 2019 · 3 comments · Fixed by #883
Closed

Improve documentation on fibers #830

lenkis opened this issue Jul 16, 2019 · 3 comments · Fixed by #883
Assignees
Labels
bug Something isn't working need feedback [special status] On hold, awaiting feedback reference [location] Tarantool manual, Reference part server [area] Task relates to Tarantool's server (core) functionality

Comments

@lenkis
Copy link
Contributor

lenkis commented Jul 16, 2019

(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
Copy link
Contributor Author

lenkis commented Jul 16, 2019

(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 я даже не знаю что ещё будет работать с данным файбером

@lenkis lenkis added 1.10 bug Something isn't working reference [location] Tarantool manual, Reference part server [area] Task relates to Tarantool's server (core) functionality labels Jul 16, 2019
izmalk pushed a commit that referenced this issue Aug 20, 2019
Summirized the cancelled status issues in one NOTE and changed an example in fiber:cancel() description.
Also depended with #831  and #829
@izmalk izmalk added the need feedback [special status] On hold, awaiting feedback label Aug 20, 2019
izmalk pushed a commit that referenced this issue Aug 23, 2019
Updated NOTE text after discussion.
@izmalk
Copy link
Contributor

izmalk commented Aug 23, 2019

@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
Copy link
Member

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.

pgulutzan added a commit that referenced this issue Aug 30, 2019
izmalk pushed a commit that referenced this issue Sep 2, 2019
Further improvement to cancell status and recommendations on canceled fibers termination
izmalk pushed a commit that referenced this issue Sep 2, 2019
Fixed wording.
lenkis pushed a commit that referenced this issue Sep 2, 2019
Fix gh-825 feedback: Submodule box.index
Fix gh-857 feedback: Модель данных
Fix gh-856 feedback: Access control
Fix gh-853 feedback: Functions for transaction management
Fix gh-848 feedback: Submodule box.index
Fix gh-834 Использование бинарного пакета
Fix gh-867 feedback: Access control
Fix gh-866 feedback: Триггеры
Fix gh-865 feedback: Триггеры
Fix gh-864 feedback: Рекомендации по Lua-синтаксису
Fix gh-861 feedback: Модуль http
Fix gh-869 Сonfusing wording in box.backup page
Fix gh-860 vshard.router/storage.sync miss return value documentation
Fix gh-830 Improve documentation on fibers
Fix gh-850 Add more info about connectors
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working need feedback [special status] On hold, awaiting feedback reference [location] Tarantool manual, Reference part server [area] Task relates to Tarantool's server (core) functionality
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants