facebook / facebook/folly

Modify folly/fibers quick-guide example to clarify usage of EventBase::loop() with FiberManager

Open
#1,945 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
30.5k
Forks
5.9k
PR merge metrics
No merged PRs in 30d

Description

The current example in the folly/fibers [quick-guide documentation](https://github.com/facebook/folly/tree/main/folly/fibers#quick-guide) shows the usage of `folly::EventBase::loop()` in a way that can be confusing to new users of the library.
Specifically, the example shows calling `loop()` twice, without sufficient explanation of why this is necessary.

After some investigation, I learned that `loop()` blocks the calling thread until all currently scheduled tasks are complete. Therefore, calling `loop()` multiple times in a row can lead to unexpected behavior and should be avoided.

I suggest modifying the example code to make this behavior more clear to new users.
One possible modification would be to remove the second `evb.loop()` call entirely, and add another task to post baton like below.
This would better illustrate the intended usage of the EventBase and FiberManager classes.
```
...
folly::EventBase evb;
auto& fiberManager = folly::fibers::getFiberManager(evb);
folly::fibers::Baton baton;

fiberManager.addTask([&]() {
std::cout << "Task: start" << std::endl;
baton.wait();
std::cout << "Task: after baton.wait()" << std::endl;
});

fiberManager.addTask([&]() {
baton.post();
std::cout << "Baton posted" << std::endl;
});

evb.loop();

...
```

Thank you for considering this request.

Contributor guide

Open the contributing guide

Research direction

Start with the fibers quick-guide documentation linked in the issue and inspect the example's EventBase::loop() calls. Clarify the blocking behavior and show the intended task scheduling, then verify that the example consistently demonstrates one loop invocation and remains understandable to new users.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.