diff options
author | Mike Pall <mike> | 2021-08-12 21:10:13 +0200 |
---|---|---|
committer | Mike Pall <mike> | 2021-08-12 21:27:58 +0200 |
commit | 15ed84bd499b3ecdba9f431f2d24696a313227e4 (patch) | |
tree | 637662b1edce646fec939e8bf75685a09e374656 /doc | |
parent | 983d66b8c5032b421e0f5fe8d39e9930bceb7031 (diff) | |
download | luajit-15ed84bd499b3ecdba9f431f2d24696a313227e4.tar.gz luajit-15ed84bd499b3ecdba9f431f2d24696a313227e4.tar.bz2 luajit-15ed84bd499b3ecdba9f431f2d24696a313227e4.zip |
String buffers, part 4a: Add metatable serialization dictionary.
Sponsored by fmad.io.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ext_buffer.html | 45 |
1 files changed, 28 insertions, 17 deletions
diff --git a/doc/ext_buffer.html b/doc/ext_buffer.html index 2443fc90..63c2efe3 100644 --- a/doc/ext_buffer.html +++ b/doc/ext_buffer.html | |||
@@ -127,7 +127,7 @@ space. | |||
127 | <p> | 127 | <p> |
128 | Buffers operate like a FIFO (first-in first-out) data structure. Data | 128 | Buffers operate like a FIFO (first-in first-out) data structure. Data |
129 | can be appended (written) to the end of the buffer and consumed (read) | 129 | can be appended (written) to the end of the buffer and consumed (read) |
130 | from the front of the buffer. These operations can be freely mixed. | 130 | from the front of the buffer. These operations may be freely mixed. |
131 | </p> | 131 | </p> |
132 | <p> | 132 | <p> |
133 | The buffer space that holds the characters is managed automatically | 133 | The buffer space that holds the characters is managed automatically |
@@ -199,7 +199,7 @@ may be reused. | |||
199 | <h3 id="buffer_free"><tt>buf = buf:free()</tt></h3> | 199 | <h3 id="buffer_free"><tt>buf = buf:free()</tt></h3> |
200 | <p> | 200 | <p> |
201 | The buffer space of the buffer object is freed. The object itself | 201 | The buffer space of the buffer object is freed. The object itself |
202 | remains intact, empty and it may be reused. | 202 | remains intact, empty and may be reused. |
203 | </p> | 203 | </p> |
204 | <p> | 204 | <p> |
205 | Note: you normally don't need to use this method. The garbage collector | 205 | Note: you normally don't need to use this method. The garbage collector |
@@ -404,8 +404,8 @@ speed is mostly constrained by object creation cost. | |||
404 | </p> | 404 | </p> |
405 | <p> | 405 | <p> |
406 | The serializer handles most Lua types, common FFI number types and | 406 | The serializer handles most Lua types, common FFI number types and |
407 | nested structures. Functions, thread objects, other FFI cdata, full | 407 | nested structures. Functions, thread objects, other FFI cdata and full |
408 | userdata and associated metatables cannot be serialized (yet). | 408 | userdata cannot be serialized (yet). |
409 | </p> | 409 | </p> |
410 | <p> | 410 | <p> |
411 | The encoder serializes nested structures as trees. Multiple references | 411 | The encoder serializes nested structures as trees. Multiple references |
@@ -461,21 +461,31 @@ commonly occur as table keys of objects you are serializing. These keys | |||
461 | are compactly encoded as indexes during serialization. A well chosen | 461 | are compactly encoded as indexes during serialization. A well chosen |
462 | dictionary saves space and improves serialization performance. | 462 | dictionary saves space and improves serialization performance. |
463 | </li> | 463 | </li> |
464 | <li> | ||
465 | <tt>metatable</tt> is a Lua table holding a <b>dictionary of metatables</b> | ||
466 | for the table objects you are serializing. | ||
467 | </li> | ||
464 | </ul> | 468 | </ul> |
465 | <p> | 469 | <p> |
466 | <tt>dict</tt> needs to be an array of strings, starting at index 1 and | 470 | <tt>dict</tt> needs to be an array of strings and <tt>metatable</tt> needs |
467 | without holes (no <tt>nil</tt> inbetween). The table is anchored in the | 471 | to be an array of tables. Both starting at index 1 and without holes (no |
468 | buffer object and internally modified into a two-way index (don't do | 472 | <tt>nil</tt> inbetween). The tables are anchored in the buffer object and |
469 | this yourself, just pass a plain array). The table must not be modified | 473 | internally modified into a two-way index (don't do this yourself, just pass |
470 | after it has been passed to <tt>buffer.new()</tt>. | 474 | a plain array). The tables must not be modified after they have been passed |
475 | to <tt>buffer.new()</tt>. | ||
476 | </p> | ||
477 | <p> | ||
478 | The <tt>dict</tt> and <tt>metatable</tt> tables used by the encoder and | ||
479 | decoder must be the same. Put the most common entries at the front. Extend | ||
480 | at the end to ensure backwards-compatibility — older encodings can | ||
481 | then still be read. You may also set some indexes to <tt>false</tt> to | ||
482 | explicitly drop backwards-compatibility. Old encodings that use these | ||
483 | indexes will throw an error when decoded. | ||
471 | </p> | 484 | </p> |
472 | <p> | 485 | <p> |
473 | The <tt>dict</tt> tables used by the encoder and decoder must be the | 486 | Metatables that are not found in the <tt>metatable</tt> dictionary are |
474 | same. Put the most common entries at the front. Extend at the end to | 487 | ignored when encoding. Decoding returns a table with a <tt>nil</tt> |
475 | ensure backwards-compatibility — older encodings can then still be | 488 | metatable. |
476 | read. You may also set some indexes to <tt>false</tt> to explicitly drop | ||
477 | backwards-compatibility. Old encodings that use these indexes will throw | ||
478 | an error when decoded. | ||
479 | </p> | 489 | </p> |
480 | <p> | 490 | <p> |
481 | Note: parsing and preparation of the options table is somewhat | 491 | Note: parsing and preparation of the options table is somewhat |
@@ -564,7 +574,7 @@ suffix. | |||
564 | <pre> | 574 | <pre> |
565 | object → nil | false | true | 575 | object → nil | false | true |
566 | | null | lightud32 | lightud64 | 576 | | null | lightud32 | lightud64 |
567 | | int | num | tab | 577 | | int | num | tab | tab_mt |
568 | | int64 | uint64 | complex | 578 | | int64 | uint64 | complex |
569 | | string | 579 | | string |
570 | 580 | ||
@@ -585,13 +595,14 @@ tab → 0x08 // Empty table | |||
585 | | 0x0b a.U a*object h.U h*{object object} // Mixed | 595 | | 0x0b a.U a*object h.U h*{object object} // Mixed |
586 | | 0x0c a.U (a-1)*object // 1-based array | 596 | | 0x0c a.U (a-1)*object // 1-based array |
587 | | 0x0d a.U (a-1)*object h.U h*{object object} // Mixed | 597 | | 0x0d a.U (a-1)*object h.U h*{object object} // Mixed |
598 | tab_mt → 0x0e (index-1).U tab // Metatable dict entry | ||
588 | 599 | ||
589 | int64 → 0x10 int.L // FFI int64_t | 600 | int64 → 0x10 int.L // FFI int64_t |
590 | uint64 → 0x11 uint.L // FFI uint64_t | 601 | uint64 → 0x11 uint.L // FFI uint64_t |
591 | complex → 0x12 re.L im.L // FFI complex | 602 | complex → 0x12 re.L im.L // FFI complex |
592 | 603 | ||
593 | string → (0x20+len).U len*char.B | 604 | string → (0x20+len).U len*char.B |
594 | | 0x0f (index-1).U // Dict entry | 605 | | 0x0f (index-1).U // String dict entry |
595 | 606 | ||
596 | .B = 8 bit | 607 | .B = 8 bit |
597 | .I = 32 bit little-endian | 608 | .I = 32 bit little-endian |