tarantool / tarantool/doc

Document `read_view.with` method

Open Beginner friendly
#5,721 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.