Skip to content
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

Document the Buffer/Batch constraints on tower-batch #1668

Closed
teor2345 opened this issue Feb 3, 2021 · 2 comments
Closed

Document the Buffer/Batch constraints on tower-batch #1668

teor2345 opened this issue Feb 3, 2021 · 2 comments
Labels
A-docs Area: Documentation C-bug Category: This is a bug

Comments

@teor2345
Copy link
Contributor

teor2345 commented Feb 3, 2021

Is your feature request related to a problem? Please describe.

tower-batch has a very similar implementation to tower::buffer:
https://github.com/ZcashFoundation/zebra/blob/main/tower-batch/src/service.rs#L97
https://docs.rs/tower/0.4.4/src/tower/buffer/service.rs.html#112

Like tower::buffer:

  • If lots of tasks with data dependencies use a Batch with a small bound, the Batch can hang.
  • Batches with small bounds can also limit concurrency, particularly if the underlying service does a lot of work in its call.

Describe the solution you'd like

Document these risks, but be more detailed than tower::buffer:
https://docs.rs/tower/0.4.4/tower/buffer/struct.Buffer.html#a-note-on-choosing-a-bound

We probably want to add the details at module level, then add a summary on new and poll_ready:
https://github.com/ZcashFoundation/zebra/blob/main/tower-batch/src/lib.rs
https://github.com/ZcashFoundation/zebra/blob/main/tower-batch/src/service.rs#L53
https://github.com/ZcashFoundation/zebra/blob/main/tower-batch/src/service.rs#L87

Describe alternatives you've considered

Do nothing. Callers risk hangs in tower-buffer.

Additional context

See #1593 for the overall Buffer hang issue, analysis, and design patterns.

@teor2345 teor2345 added C-bug Category: This is a bug A-docs Area: Documentation S-needs-triage Status: A bug report needs triage P-Medium labels Feb 3, 2021
@mpguerra mpguerra removed the S-needs-triage Status: A bug report needs triage label Feb 4, 2021
@teor2345
Copy link
Contributor Author

This task has been revised based on the fixes to the underlying Buffer issue, see #1593 for details.

@teor2345 teor2345 changed the title Document the poll_ready/call hang risk on tower-batch Document the Buffer/Batch hang risk on tower-batch Feb 15, 2021
@teor2345 teor2345 changed the title Document the Buffer/Batch hang risk on tower-batch Document the Buffer/Batch constraints on tower-batch Feb 15, 2021
@teor2345
Copy link
Contributor Author

The current settings seem fine.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation C-bug Category: This is a bug
Projects
None yet
Development

No branches or pull requests

2 participants