tarantool / tarantool/doc

Read views in application threads

Open
#5,709 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

A database read view can now be accessed from an application thread.
To do that, you need to pass the read view id to the thread where it's
going to be used and open the read view by id there, for example:

local threads = require('experimental.threads')

box.cfg{app_threads = 1}

box.schema.space.create('test')
box.space.test:create_index('primary')
box.space.test:replace({1, 'x'})
box.space.test:replace({2, 'y'})
box.space.test:replace({3, 'z'})

local rv = box.read_view.open({name = 'shared_read_view'})
threads.eval('app', [[
    local rv = box.read_view.open({id = ...})
    return rv.space.test:select()
]], {rv.id})

Note, a new read view still can be created only in the main thread -
calling box.read_view.open() without an id in an application thread
would fail. Also, box.read_view.list() called in an application thread
only returns read views that were opened in that thread while a full list
of all open read views (including read views used for system purposes)
can only be retrieved in the main thread^1.

If a read view is used in an application thread, closing it in the main
thread will not delete the read view immediately: instead the read view
will be switch to the close_pending state. Just like a closed read
view, a read view in the close_pending state can't be used in the main
thread or reopened in another thread. However, it still can be used in
the application threads where it was opened before it switched to this
state. Once the last thread using the read view closes it (or the read
view object is closed implicitly by the Lua garbage collector), the read
view will be deleted globally.

Requested by @locker in https://github.com/tarantool/tarantool/commit/082639265440ff02d183066c0580302bc6405155.

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

Start by locating the existing documentation for box.read_view.open(), box.read_view.list(), and experimental.threads. Add the application-thread usage example and document the id requirement, listing limits, and close_pending behavior. Done means the documented behavior matches the issue and the example clearly shows sharing a read view between threads.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
databases, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.