Documentation Source Text

Check-in [21168dec96]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Comment:Improved background information on the bytecode engine.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 21168dec9629debd480c85cb8046fa905af562449939cc702d09822d97d1248e
User & Date: drh 2017-04-29 16:55:34
Further improvements to the opcode.html document. check-in: 1f4f0600ef user: drh tags: trunk
Improved background information on the bytecode engine. check-in: 21168dec96 user: drh tags: trunk
Update to the flattening optimization description in the optoverview.html page. Add a new bullet to the change log for 3.19.0. check-in: d26b238e7e user: drh tags: trunk
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/

   170    170   registers.  For instructions that operate on b-tree cursors,
   171    171   the P1 operand is usually the cursor number.
   172    172   For jump instructions, P2 is usually the jump destination.
   173    173   P4 may be a 32-bit signed integer, a 64-bit signed integer, a
   174    174   64-bit floating point value, a string literal, a Blob literal,
   175    175   a pointer to a collating sequence comparison function, or a
   176    176   pointer to the implementation of an application-defined SQL
   177         -function, or various other things.  P5 is an unsigned character
   178         -normally used as a flag.  Bits of the P5 flag can sometimes affect
          177  +function, or various other things.  P5 is an 16-bit unsigned integer
          178  +normally used to hold flags.  Bits of the P5 flag can sometimes affect
   179    179   the opcode in subtle ways.  For example, if the 
   180         -SQLITE_NULLEQ (0x80) bit of the P5 operand
          180  +SQLITE_NULLEQ (0x0080) bit of the P5 operand
   181    181   is set on the OP_Eq opcode, then the NULL values compare
   182    182   equal to one another.  Otherwise NULL values compare different
   183    183   from one another.
   184    184   }
   185    185   </tcl>
   186    186   
   187    187   <p>Some opcodes use all five operands.  Some opcodes use
   242    242   Most opcodes refer to at least one register.
   243    243   
   244    244   <p>The number of registers in a single prepared statement is fixed
   245    245   at compile-time.  The content of all registers is cleared when
   246    246   a prepared statement is [sqlite3_reset()|reset] or
   247    247   [sqlite3_finalize()|finalized].
   248    248   
          249  +<p>The internal Mem object stores the value for a single register.
          250  +The abstract [sqlite3_value] object that is exposed in the API is really
          251  +just a Mem object or register.
          252  +
   249    253   <h2>B-Tree Cursors</h2>
   250    254   
   251    255   <tcl>
   252    256   LinkOpcodeNames {
   253    257   <p>A prepared statement can have
   254    258   zero or more open cursors.  Each cursor is identified by a
   255    259   small integer, which is usually the P1 parameter to the opcode
   265    269   advance the cursor to the next entry in the table
   266    270   (ex: OP_Next or OP_Prev), and so forth.
   267    271   All cursors are automatically
   268    272   closed when the prepared statement is [sqlite3_reset()|reset] or
   269    273   [sqlite3_finalize()|finalized].
   270    274   }
   271    275   </tcl>
          276  +
          277  +<h2>Subroutines, Coroutines, and Subprograms</h2>
          278  +
          279  +<p>The bytecode engine has no stack on which to store the return address
          280  +of a subroutine.  Return addresses must be stored in registers.
          281  +Hence, bytecode subroutines are not reentrant.
          282  +
          283  +<tcl>
          284  +LinkOpcodeNames {
          285  +<p>The OP_Gosub opcode stores the current program counter into
          286  +register P1 then jumps to address P2.  The OP_Return opcode jumps
          287  +to address P1+1.  Hence, every subroutine is associated with two integers:
          288  +the address of the entry point in the subroutine and the register number
          289  +that is used to hold the return address.
          290  +
          291  +<p>The OP_Yield opcode swaps the value of the program counter with
          292  +the integer value in register P1.  This opcode is used to implement
          293  +coroutines.  Coroutines are often used to implement subqueries from
          294  +which content is pulled on an as-needed basis.
          295  +}
          296  +</tcl>
          297  +
          298  +<p>[CREATE TRIGGER|Triggers] need to be reentrant.
          299  +
          300  +<tcl>
          301  +LinkOpcodeNames {
          302  +Since bytecode
          303  +subroutines are not reentrant a different mechanism must be used to
          304  +implmeent triggers.  Each trigger is implemented using a separate bytecode
          305  +pragram with its own opcodes, program counter, and register set.  The
          306  +OP_Program opcode invokes the trigger subprogram.  The OP_Program instruction
          307  +allocates and initializes a fresh register set for each invocation of the
          308  +subprogram, so subprograms can be reentrant and recursive.  The
          309  +OP_Param opcode is used by subprograms to access content in registers
          310  +of the calling bytecode program.
          311  +}
          312  +</tcl>
   272    313   
   273    314   <h1>Viewing The Bytecode</h1>
   274    315   
   275    316   <p>Every SQL statement that SQLite interprets results in a program
   276    317   for the virtual machine.  But if the SQL statement begins with
   277    318   the keyword [EXPLAIN] the virtual machine will not execute the
   278    319   program.  Instead, the instructions of the program will be returned,