Document `read_view.with` method
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 15
- Forks
- 49
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 3
Description
The new read view method :with() executes a function with a guarantee
that the read view object will remain operational until the function
returns, even if it's closed from another fiber.
Usage:
local rv = box.read_view.open()
-- ...
rv:with(function()
-- do something with the read view
end)
If the read view object is closed (that is :close() is called) while
a function passed to :with() is still running, the read view status
will change to close_pending and remain such until the function
returns, after which it will change to closed and the read view
resources will be freed. A read view in the close_pending state can
be accessed just like an open read view but calling :with() on it will
raise an error.
A function called using :with() is passed the read view object as the
first argument, which may be used instead of capturing it in an upvalue,
and the rest of the arguments passed to :with() after the function.
The :with() method returns the same value as the called function.
If the called function raises an error, the error is re-raised.
For example:
local function read_view_avg(rv, space_name, field_name)
local count = 0
local sum = 0
for _, tuple in rv.space[space_name]:pairs() do
sum = sum + tuple[field_name]
count = count + 1
if count % 1000 == 0 then
-- yield once in a while so as not to block other fibers
fiber.yield()
end
end
return sum / count
end
local rv = box.read_view.open()
local avg = rv:with(read_view_avg, 'my_space', 'some_field')
Requested by @locker in https://github.com/tarantool/tarantool/commit/2952a9afcaed1b7ae33267cdd703e98c365bcf3a.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Search the Tarantool documentation for the existing box.read_view.open and read view API reference, then place the new :with() method alongside it. Document its arguments, callback behavior, return values, error propagation, and close_pending semantics using the issue examples; done means the method is discoverable and its documented behavior matches the request.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- lua
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100