From 35dff7ca2cfe5e54d31221ed8947f467e5f8fd21 Mon Sep 17 00:00:00 2001 From: Pekka Enberg Date: Fri, 26 Jul 2024 10:21:44 +0300 Subject: [PATCH] core: Add module-level docs for translate and vdbe Let's add module-level documentation for the code generator in `translate` and the virtual machine in `vdbe`, which are two major subsystems in the database engine that developers work on mostly. --- core/translate/mod.rs | 9 +++++++++ core/vdbe/mod.rs | 19 +++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/core/translate/mod.rs b/core/translate/mod.rs index 9eb2859ae..6b95e30a4 100644 --- a/core/translate/mod.rs +++ b/core/translate/mod.rs @@ -1,3 +1,12 @@ +//! The VDBE bytecode code generator. +//! +//! This module is responsible for translating the SQL AST into a sequence of +//! instructions for the VDBE. The VDBE is a register-based virtual machine that +//! executes bytecode instructions. This code generator is responsible for taking +//! the SQL AST and generating the corresponding VDBE instructions. For example, +//! a SELECT statement will be translated into a sequence of instructions that +//! will read rows from the database and filter them according to a WHERE clause. + pub(crate) mod expr; pub(crate) mod select; pub(crate) mod where_clause; diff --git a/core/vdbe/mod.rs b/core/vdbe/mod.rs index f32d6cae8..10e764f77 100644 --- a/core/vdbe/mod.rs +++ b/core/vdbe/mod.rs @@ -1,3 +1,22 @@ +//! The virtual database engine (VDBE). +//! +//! The VDBE is a register-based virtual machine that execute bytecode +//! instructions that represent SQL statements. When an application prepares +//! an SQL statement, the statement is compiled into a sequence of bytecode +//! instructions that perform the needed operations, such as reading or +//! writing to a b-tree, sorting, or aggregating data. +//! +//! The instruction set of the VDBE is similar to SQLite's instruction set, +//! but with the exception that bytecodes that perform I/O operations are +//! return execution back to the caller instead of blocking. This is because +//! Limbo is designed for applications that need high concurrency such as +//! serverless runtimes. In addition, asynchronous I/O makes storage +//! disaggregation easier. +//! +//! You can find a full list of SQLite opcodes at: +//! +//! https://www.sqlite.org/opcode.html + pub mod builder; pub mod explain; pub mod sorter;