Documentation Source Text

Check-in [21168dec96]
Login

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

Overview
Comment:Improved background information on the bytecode engine.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 21168dec9629debd480c85cb8046fa905af562449939cc702d09822d97d1248e
User & Date: drh 2017-04-29 16:55:34.919
Context
2017-04-29
18:03
Further improvements to the opcode.html document. (check-in: 1f4f0600ef user: drh tags: trunk)
16:55
Improved background information on the bytecode engine. (check-in: 21168dec96 user: drh tags: trunk)
2017-04-18
11:52
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)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/opcode.in.
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
registers.  For instructions that operate on b-tree cursors,
the P1 operand is usually the cursor number.
For jump instructions, P2 is usually the jump destination.
P4 may be a 32-bit signed integer, a 64-bit signed integer, a
64-bit floating point value, a string literal, a Blob literal,
a pointer to a collating sequence comparison function, or a
pointer to the implementation of an application-defined SQL
function, or various other things.  P5 is an unsigned character
normally used as a flag.  Bits of the P5 flag can sometimes affect
the opcode in subtle ways.  For example, if the 
SQLITE_NULLEQ (0x80) bit of the P5 operand
is set on the OP_Eq opcode, then the NULL values compare
equal to one another.  Otherwise NULL values compare different
from one another.
}
</tcl>

<p>Some opcodes use all five operands.  Some opcodes use







|
|

|







170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
registers.  For instructions that operate on b-tree cursors,
the P1 operand is usually the cursor number.
For jump instructions, P2 is usually the jump destination.
P4 may be a 32-bit signed integer, a 64-bit signed integer, a
64-bit floating point value, a string literal, a Blob literal,
a pointer to a collating sequence comparison function, or a
pointer to the implementation of an application-defined SQL
function, or various other things.  P5 is an 16-bit unsigned integer
normally used to hold flags.  Bits of the P5 flag can sometimes affect
the opcode in subtle ways.  For example, if the 
SQLITE_NULLEQ (0x0080) bit of the P5 operand
is set on the OP_Eq opcode, then the NULL values compare
equal to one another.  Otherwise NULL values compare different
from one another.
}
</tcl>

<p>Some opcodes use all five operands.  Some opcodes use
242
243
244
245
246
247
248




249
250
251
252
253
254
255
Most opcodes refer to at least one register.

<p>The number of registers in a single prepared statement is fixed
at compile-time.  The content of all registers is cleared when
a prepared statement is [sqlite3_reset()|reset] or
[sqlite3_finalize()|finalized].





<h2>B-Tree Cursors</h2>

<tcl>
LinkOpcodeNames {
<p>A prepared statement can have
zero or more open cursors.  Each cursor is identified by a
small integer, which is usually the P1 parameter to the opcode







>
>
>
>







242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
Most opcodes refer to at least one register.

<p>The number of registers in a single prepared statement is fixed
at compile-time.  The content of all registers is cleared when
a prepared statement is [sqlite3_reset()|reset] or
[sqlite3_finalize()|finalized].

<p>The internal Mem object stores the value for a single register.
The abstract [sqlite3_value] object that is exposed in the API is really
just a Mem object or register.

<h2>B-Tree Cursors</h2>

<tcl>
LinkOpcodeNames {
<p>A prepared statement can have
zero or more open cursors.  Each cursor is identified by a
small integer, which is usually the P1 parameter to the opcode
265
266
267
268
269
270
271





































272
273
274
275
276
277
278
advance the cursor to the next entry in the table
(ex: OP_Next or OP_Prev), and so forth.
All cursors are automatically
closed when the prepared statement is [sqlite3_reset()|reset] or
[sqlite3_finalize()|finalized].
}
</tcl>






































<h1>Viewing The Bytecode</h1>

<p>Every SQL statement that SQLite interprets results in a program
for the virtual machine.  But if the SQL statement begins with
the keyword [EXPLAIN] the virtual machine will not execute the
program.  Instead, the instructions of the program will be returned,







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
advance the cursor to the next entry in the table
(ex: OP_Next or OP_Prev), and so forth.
All cursors are automatically
closed when the prepared statement is [sqlite3_reset()|reset] or
[sqlite3_finalize()|finalized].
}
</tcl>

<h2>Subroutines, Coroutines, and Subprograms</h2>

<p>The bytecode engine has no stack on which to store the return address
of a subroutine.  Return addresses must be stored in registers.
Hence, bytecode subroutines are not reentrant.

<tcl>
LinkOpcodeNames {
<p>The OP_Gosub opcode stores the current program counter into
register P1 then jumps to address P2.  The OP_Return opcode jumps
to address P1+1.  Hence, every subroutine is associated with two integers:
the address of the entry point in the subroutine and the register number
that is used to hold the return address.

<p>The OP_Yield opcode swaps the value of the program counter with
the integer value in register P1.  This opcode is used to implement
coroutines.  Coroutines are often used to implement subqueries from
which content is pulled on an as-needed basis.
}
</tcl>

<p>[CREATE TRIGGER|Triggers] need to be reentrant.

<tcl>
LinkOpcodeNames {
Since bytecode
subroutines are not reentrant a different mechanism must be used to
implmeent triggers.  Each trigger is implemented using a separate bytecode
pragram with its own opcodes, program counter, and register set.  The
OP_Program opcode invokes the trigger subprogram.  The OP_Program instruction
allocates and initializes a fresh register set for each invocation of the
subprogram, so subprograms can be reentrant and recursive.  The
OP_Param opcode is used by subprograms to access content in registers
of the calling bytecode program.
}
</tcl>

<h1>Viewing The Bytecode</h1>

<p>Every SQL statement that SQLite interprets results in a program
for the virtual machine.  But if the SQL statement begins with
the keyword [EXPLAIN] the virtual machine will not execute the
program.  Instead, the instructions of the program will be returned,