wbtiger
/
foundationdb
mirror of https://github.com/apple/foundationdb.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Convert bindings spec files to markdown 

* The initial plaintext file converts nicely - this just converts operations to small headers and uses &lt; and &gt; to make sure text in <> shows up
* Use inline code in a few places where it makes sense
This commit is contained in:
Amanda Aizuss 2018-04-20 14:31:28 -07:00 committed by Alec Grieser
parent 7bb332ab64
commit 256d7d030d
No known key found for this signature in database
GPG Key ID: CAF63551C60D3462
2 changed files with 123 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
bindings/bindingtester/spec/bindingApiTester.txt → bindings/bindingtester/spec/bindingApiTester.md
View File

@ -5,7 +5,7 @@ Your API test program must implement a simple stack machine that exercises the
FoundationDB API. The program is invoked with two or three arguments. The first
argument is a prefix that is the first element of a tuple, the second is the
API version, and the third argument is the path to a cluster file. If the
third argument is not specified, your program may assume that fdb.open() will
third argument is not specified, your program may assume that `fdb.open()` will
succeed with no arguments (an fdb.cluster file will exist in the current
directory). Otherwise, your program should connect to the cluster specified
by the given cluster file.
@ -47,41 +47,41 @@ instructions:
Data Operations
---------------
PUSH <item>
#### PUSH &lt;item&gt;
Pushes the provided item onto the stack.
DUP
#### DUP
Duplicates the top item on the stack. The instruction number for the
duplicate item should be the same as the original.
EMPTY_STACK
#### EMPTY_STACK
Discards all items in the stack.
SWAP
#### SWAP
Pops the top item off of the stack as INDEX. Swaps the items in the stack at
depth 0 and depth INDEX. Does not modify the instruction numbers of the
swapped items.
POP
#### POP
Pops and discards the top item on the stack.
SUB
#### SUB
Pops the top two items off of the stack as A and B and then pushes the
difference (A-B) onto the stack. A and B may be assumed to be integers.
CONCAT
#### CONCAT
Pops the top two items off the stack as A and B and then pushes the
concatenation of A and B onto the stack. A and B can be assumed to
be of the same type and will be either byte strings or unicode strings.
LOG_STACK
#### LOG_STACK
Pops the top item off the stack as PREFIX. Using a new transaction with normal
retry logic, inserts a key-value pair into the database for each item in the
@ -117,7 +117,7 @@ should simulate it using an anonymous transaction. Remember that set and clear
operations must immediately commit (with appropriate retry behavior!).
Any error that bubbles out of these operations must be caught. In the event of
an error, you must push the packed tuple of the string "ERROR" and the error
an error, you must push the packed tuple of the string `"ERROR"` and the error
code (as a string, not an integer).
Some operations may allow you to push future values onto the stack. When popping
@ -132,25 +132,25 @@ futures must apply the following rules to the result:
- If the result is void (i.e. the future was just a signal of
completion), then its value should be the byte string
"RESULT_NOT_PRESENT"
`"RESULT_NOT_PRESENT"`
- If the result is from a GET operation in which no result was
returned, then its value is to be converted to the byte string
"RESULT_NOT_PRESENT"
`"RESULT_NOT_PRESENT"`
NEW_TRANSACTION
#### NEW_TRANSACTION
Creates a new transaction and stores it in the global transaction map
under the currently used transaction name.
USE_TRANSACTION
#### USE_TRANSACTION
Pop the top item off of the stack as TRANSACTION_NAME. Begin using the
transaction stored at TRANSACTION_NAME in the transaction map for future
operations. If no entry exists in the map for the given name, a new
transaction should be inserted.
ON_ERROR
#### ON_ERROR
Pops the top item off of the stack as ERROR_CODE. Passes ERROR_CODE in a
language-appropriate way to the on_error method of current transaction
@ -158,13 +158,13 @@ ON_ERROR
the error out as indicated above. May optionally push a future onto the
stack.
GET (_SNAPSHOT, _DATABASE)
#### GET (_SNAPSHOT, _DATABASE)
Pops the top item off of the stack as KEY and then looks up KEY in the
database using the get() method. May optionally push a future onto the
stack.
GET_KEY (_SNAPSHOT, _DATABASE)
#### GET_KEY (_SNAPSHOT, _DATABASE)
Pops the top four items off of the stack as KEY, OR_EQUAL, OFFSET, PREFIX
and then constructs a key selector. This key selector is then resolved
@ -173,7 +173,7 @@ GET_KEY (_SNAPSHOT, _DATABASE)
is pushed onto the stack. If RESULT > PREFIX, then strinc(PREFIX) is pushed
onto the stack. May optionally push a future onto the stack.
GET_RANGE (_SNAPSHOT, _DATABASE)
#### GET_RANGE (_SNAPSHOT, _DATABASE)
Pops the top five items off of the stack as BEGIN_KEY, END_KEY, LIMIT,
REVERSE and STREAMING_MODE. Performs a range read in a language-appropriate
@ -181,13 +181,13 @@ GET_RANGE (_SNAPSHOT, _DATABASE)
packed into a tuple as [k1,v1,k2,v2,...,kn,vn], and this single packed value
is pushed onto the stack.
GET_RANGE_STARTS_WITH (_SNAPSHOT, _DATABASE)
#### GET_RANGE_STARTS_WITH (_SNAPSHOT, _DATABASE)
Pops the top four items off of the stack as PREFIX, LIMIT, REVERSE and
STREAMING_MODE. Performs a prefix range read in a language-appropriate way
using these parameters. Output is pushed onto the stack as with GET_RANGE.
GET_RANGE_SELECTOR (_SNAPSHOT, _DATABASE)
#### GET_RANGE_SELECTOR (_SNAPSHOT, _DATABASE)
Pops the top ten items off of the stack as BEGIN_KEY, BEGIN_OR_EQUAL,
BEGIN_OFFSET, END_KEY, END_OR_EQUAL, END_OFFSET, LIMIT, REVERSE,
@ -197,87 +197,87 @@ GET_RANGE_SELECTOR (_SNAPSHOT, _DATABASE)
is pushed onto the stack as with GET_RANGE, excluding any keys that do not
begin with PREFIX.
GET_READ_VERSION (_SNAPSHOT)
#### GET_READ_VERSION (_SNAPSHOT)
Gets the current read version and stores it in the internal stack machine
state as the last seen version. Pushed the string "GOT_READ_VERSION" onto
the stack.
GET_VERSIONSTAMP
#### GET_VERSIONSTAMP
Calls get_versionstamp and pushes the resulting future onto the stack.
SET (_DATABASE)
#### SET (_DATABASE)
Pops the top two items off of the stack as KEY and VALUE. Sets KEY to have
the value VALUE. A SET_DATABASE call may optionally push a future onto the
stack.
SET_READ_VERSION
#### SET_READ_VERSION
Sets the current transaction read version to the internal state machine last
seen version.
CLEAR (_DATABASE)
#### CLEAR (_DATABASE)
Pops the top item off of the stack as KEY and then clears KEY from the
database. A CLEAR_DATABASE call may optionally push a future onto the stack.
CLEAR_RANGE (_DATABASE)
#### CLEAR_RANGE (_DATABASE)
Pops the top two items off of the stack as BEGIN_KEY and END_KEY. Clears the
range of keys from BEGIN_KEY to END_KEY in the database. A
CLEAR_RANGE_DATABASE call may optionally push a future onto the stack.
CLEAR_RANGE_STARTS_WITH (_DATABASE)
#### CLEAR_RANGE_STARTS_WITH (_DATABASE)
Pops the top item off of the stack as PREFIX and then clears all keys from
the database that begin with PREFIX. A CLEAR_RANGE_STARTS_WITH_DATABASE call
may optionally push a future onto the stack.
ATOMIC_OP (_DATABASE)
#### ATOMIC_OP (_DATABASE)
Pops the top three items off of the stack as OPTYPE, KEY, and VALUE.
Performs the atomic operation described by OPTYPE upon KEY with VALUE. An
ATOMIC_OP_DATABASE call may optionally push a future onto the stack.
READ_CONFLICT_RANGE and WRITE_CONFLICT_RANGE
#### READ_CONFLICT_RANGE and WRITE_CONFLICT_RANGE
Pops the top two items off of the stack as BEGIN_KEY and END_KEY. Adds a
read conflict range or write conflict range from BEGIN_KEY to END_KEY.
Pushes the byte string "SET_CONFLICT_RANGE" onto the stack.
READ_CONFLICT_KEY and WRITE_CONFLICT_KEY
#### READ_CONFLICT_KEY and WRITE_CONFLICT_KEY
Pops the top item off of the stack as KEY. Adds KEY as a read conflict key
or write conflict key. Pushes the byte string "SET_CONFLICT_KEY" onto the
stack.
DISABLE_WRITE_CONFLICT
#### DISABLE_WRITE_CONFLICT
Sets the NEXT_WRITE_NO_WRITE_CONFLICT_RANGE transaction option on the
current transaction. Does not modify the stack.
COMMIT
#### COMMIT
Commits the current transaction (with no retry behavior). May optionally
push a future onto the stack.
RESET
#### RESET
Resets the current transaction.
CANCEL
#### CANCEL
Cancels the current transaction.
GET_COMMITTED_VERSION
#### GET_COMMITTED_VERSION
Gets the committed version from the current transaction and stores it in the
internal stack machine state as the last seen version. Pushes the byte
string "GOT_COMMITTED_VERSION" onto the stack.
WAIT_FUTURE
#### WAIT_FUTURE
Pops the top item off the stack and pushes it back on. If the top item on
the stack is a future, this will have the side effect of waiting on the
@ -287,13 +287,13 @@ WAIT_FUTURE
Tuple Operations
----------------
TUPLE_PACK
#### TUPLE_PACK
Pops the top item off of the stack as N. Pops the next N items off of the
stack and packs them as the tuple [item0,item1,...,itemN], and then pushes
this single packed value onto the stack.
TUPLE_PACK_WITH_VERSIONSTAMP
#### TUPLE_PACK_WITH_VERSIONSTAMP
Pops the top item off of the stack as a byte string prefix. Pops the next item
off of the stack as N. Pops the next N items off of the stack and packs them
@ -307,20 +307,20 @@ TUPLE_PACK_WITH_VERSIONSTAMP
do not contain a 'Versionstamp' tuple-type do not have to implement this
operation.)
TUPLE_UNPACK
#### TUPLE_UNPACK
Pops the top item off of the stack as PACKED, and then unpacks PACKED into a
tuple. For each element of the tuple, packs it as a new tuple and pushes it
onto the stack.
TUPLE_RANGE
#### TUPLE_RANGE
Pops the top item off of the stack as N. Pops the next N items off of the
stack, and passes these items as a tuple (or array, or language-appropriate
structure) to the tuple range method. Pushes the begin and end elements of
the returned range onto the stack.
TUPLE_SORT
#### TUPLE_SORT
Pops the top item off of the stack as N. Pops the next N items off of the
stack as packed tuples (i.e., byte strings), unpacks them, sorts the tuples,
@ -330,25 +330,25 @@ TUPLE_SORT
use that to sort. Otherwise, it should sort them lexicographically by
their byte representation. The choice of function should not affect final sort order.
ENCODE_FLOAT
#### ENCODE_FLOAT
Pops the top item off of the stack. This will be a byte-string of length 4
containing the IEEE 754 encoding of a float in big-endian order.
This is then converted into a float and pushed onto the stack.
ENCODE_DOUBLE
#### ENCODE_DOUBLE
Pops the top item off of the stack. This will be a byte-string of length 8
containing the IEEE 754 encoding of a double in big-endian order.
This is then converted into a double and pushed onto the stack.
DECODE_FLOAT
#### DECODE_FLOAT
Pops the top item off of the stack. This will be a single-precision float.
This is converted into a (4 byte) byte-string of its IEEE 754 representation
in big-endian order, and pushed onto the stack.
DECODE_DOUBLE
#### DECODE_DOUBLE
Pops the top item off of the stack. This will be a double-precision float.
This is converted into a (8 byte) byte-string its IEEE 754 representation
@ -358,7 +358,7 @@ DECODE_DOUBLE
Thread Operations
-----------------
START_THREAD
#### START_THREAD
Pops the top item off of the stack as PREFIX. Creates a new stack machine
instance operating on the same database as the current stack machine, but
@ -366,7 +366,7 @@ START_THREAD
state. The new stack machine should begin executing instructions concurrent
with the current stack machine through a language-appropriate mechanism.
WAIT_EMPTY
#### WAIT_EMPTY
Pops the top item off of the stack as PREFIX. Blocks execution until the
range with prefix PREFIX is not present in the database. This should be
@ -378,7 +378,7 @@ WAIT_EMPTY
Miscellaneous
-------------
UNIT_TESTS
#### UNIT_TESTS
This is called during the scripted test to allow bindings to test features
which aren't supported by the stack tester. Things currently tested in the

50
bindings/bindingtester/spec/directoryLayerTester.txt → bindings/bindingtester/spec/directoryLayerTester.md
View File

@ -10,14 +10,14 @@ Additional State and Initialization
Your tester should store three additional pieces of state.
directory list - The items in this list should be accessible by index. The list
* directory list - The items in this list should be accessible by index. The list
should support an append operation. It will be required to store Subspaces,
DirectorySubspaces, and DirectoryLayers.
directory list index - an index into the directory list of the currently active
* directory list index - an index into the directory list of the currently active
directory.
error index - the index to use when the directory at directory list index is not
* error index - the index to use when the directory at directory list index is not
present
At the beginning of the test, the list should contain just the default directory
@ -36,7 +36,7 @@ Errors
------
In the even that you encounter an error when performing a directory layer
operation, you should push the byte string: "DIRECTORY_ERROR" onto the stack. If
operation, you should push the byte string: `"DIRECTORY_ERROR"` onto the stack. If
the operation being performed was supposed to append an item to the directory
list, then a null entry should be appended instead.
@ -53,13 +53,13 @@ to pack a key).
Directory/Subspace/Layer Creation
---------------------------------
DIRECTORY_CREATE_SUBSPACE
#### DIRECTORY_CREATE_SUBSPACE
Pop 1 tuple off the stack as [path]. Pop 1 additional item as [raw_prefix].
Create a subspace with path as the prefix tuple and the specified
raw_prefix. Append it to the directory list.
DIRECTORY_CREATE_LAYER
#### DIRECTORY_CREATE_LAYER
Pop 3 items off the stack as [index1, index2, allow_manual_prefixes]. Let
node_subspace be the object in the directory list at index1 and
@ -71,7 +71,7 @@ DIRECTORY_CREATE_LAYER
If either of the two specified subspaces are null, then do not create a
directory layer and instead push null onto the directory list.
DIRECTORY_CREATE_OR_OPEN[_DATABASE]
#### DIRECTORY_CREATE_OR_OPEN[_DATABASE]
Use the current directory for this operation.
@ -79,14 +79,14 @@ DIRECTORY_CREATE_OR_OPEN[_DATABASE]
create_or_open a directory with the specified path and layer. If layer is
null, use the default value for that parameter.
DIRECTORY_CREATE[_DATABASE]
#### DIRECTORY_CREATE[_DATABASE]
Pop 1 tuple off the stack as [path]. Pop 2 additional items as
[layer, prefix]. create a directory with the specified path, layer,
and prefix. If either of layer or prefix is null, use the default value for
that parameter (layer='', prefix=null).
DIRECTORY_OPEN[_DATABASE|_SNAPSHOT]
#### DIRECTORY_OPEN[_DATABASE|_SNAPSHOT]
Use the current directory for this operation.
@ -97,14 +97,14 @@ DIRECTORY_OPEN[_DATABASE|_SNAPSHOT]
Directory Management
--------------------
DIRECTORY_CHANGE
#### DIRECTORY_CHANGE
Pop the top item off the stack as [index]. Set the current directory list
index to index. In the event that the directory at this new index is null
(as the result of a previous error), set the directory list index to the
error index.
DIRECTORY_SET_ERROR_INDEX
#### DIRECTORY_SET_ERROR_INDEX
Pop the top item off the stack as [error_index]. Set the current error index
to error_index.
@ -112,21 +112,21 @@ DIRECTORY_SET_ERROR_INDEX
Directory Operations
--------------------
DIRECTORY_MOVE[_DATABASE]
#### DIRECTORY_MOVE[_DATABASE]
Use the current directory for this operation.
Pop 2 tuples off the stack as [old_path, new_path]. Call move with the
specified old_path and new_path. Append the result onto the directory list.
DIRECTORY_MOVE_TO[_DATABASE]
#### DIRECTORY_MOVE_TO[_DATABASE]
Use the current directory for this operation.
Pop 1 tuple off the stack as [new_absolute_path]. Call moveTo with the
specified new_absolute_path. Append the result onto the directory list.
DIRECTORY_REMOVE[_DATABASE]
#### DIRECTORY_REMOVE[_DATABASE]
Use the current directory for this operation.
@ -134,7 +134,7 @@ DIRECTORY_REMOVE[_DATABASE]
tuple off the stack as [path]. Call remove, passing it path if one was
popped.
DIRECTORY_REMOVE_IF_EXISTS[_DATABASE]
#### DIRECTORY_REMOVE_IF_EXISTS[_DATABASE]
Use the current directory for this operation.
@ -142,7 +142,7 @@ DIRECTORY_REMOVE_IF_EXISTS[_DATABASE]
tuple off the stack as [path]. Call remove_if_exits, passing it path if one
was popped.
DIRECTORY_LIST[_DATABASE|_SNAPSHOT]
#### DIRECTORY_LIST[_DATABASE|_SNAPSHOT]
Use the current directory for this operation.
@ -151,7 +151,7 @@ DIRECTORY_LIST[_DATABASE|_SNAPSHOT]
Pack the resulting list of directories using the tuple layer and push the
packed string onto the stack.
DIRECTORY_EXISTS[_DATABASE|_SNAPSHOT]
#### DIRECTORY_EXISTS[_DATABASE|_SNAPSHOT]
Use the current directory for this operation.
@ -162,35 +162,35 @@ DIRECTORY_EXISTS[_DATABASE|_SNAPSHOT]
Subspace Operations
-------------------
DIRECTORY_PACK_KEY
#### DIRECTORY_PACK_KEY
Use the current directory for this operation.
Pop 1 tuple off the stack as [key_tuple]. Pack key_tuple and push the result
onto the stack.
DIRECTORY_UNPACK_KEY
#### DIRECTORY_UNPACK_KEY
Use the current directory for this operation.
Pop 1 item off the stack as [key]. Unpack key and push the resulting tuple
onto the stack one item at a time.
DIRECTORY_RANGE
#### DIRECTORY_RANGE
Use the current directory for this operation.
Pop 1 tuple off the stack as [tuple]. Create a range using tuple and push
range.begin and range.end onto the stack.
DIRECTORY_CONTAINS
#### DIRECTORY_CONTAINS
Use the current directory for this operation.
Pop 1 item off the stack as [key]. Check if the current directory contains
the specified key. Push 1 if it does and 0 if it doesn't.
DIRECTORY_OPEN_SUBSPACE
#### DIRECTORY_OPEN_SUBSPACE
Use the current directory for this operation.
@ -200,7 +200,7 @@ DIRECTORY_OPEN_SUBSPACE
Directory Logging
--------------------
DIRECTORY_LOG_SUBSPACE
#### DIRECTORY_LOG_SUBSPACE
Use the current directory for this operation.
@ -208,7 +208,7 @@ DIRECTORY_LOG_SUBSPACE
prefix + tuple.pack([dir_index]). Set key to be the result of calling
directory.key() in the current transaction.
DIRECTORY_LOG_DIRECTORY
#### DIRECTORY_LOG_DIRECTORY
Use the current directory for this operation.
@ -231,7 +231,7 @@ DIRECTORY_LOG_DIRECTORY
Other
-----
DIRECTORY_STRIP_PREFIX
#### DIRECTORY_STRIP_PREFIX
Use the current directory for this operation.