Upgrade sphinx and document test harness and code probes
This commit is contained in:
Markus Pilman
parent
57806dda91
commit
24aced6d4a
|
|
@ -69,7 +69,7 @@ release = root.find(".//{http://schemas.microsoft.com/developer/msbuild/2003}Ver
|
|||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
language = None
|
||||
language = 'en'
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
|
|
@ -185,7 +185,7 @@ html_show_copyright = True
|
|||
htmlhelp_basename = 'FoundationDB'
|
||||
|
||||
# Disable permalinks
|
||||
html_add_permalinks = ""
|
||||
html_permalinks = False
|
||||
|
||||
|
||||
# -- Options for LaTeX output --------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ from docutils.parsers.rst import directives, Directive
|
|||
|
||||
from sphinx import addnodes
|
||||
from sphinx.roles import XRefRole
|
||||
from sphinx.locale import l_, _
|
||||
from sphinx.locale import _
|
||||
from sphinx.domains import Domain, ObjType, Index
|
||||
from sphinx.directives import ObjectDescription
|
||||
from sphinx.util.nodes import make_refnode
|
||||
|
|
@ -83,18 +83,18 @@ class RubyObject(ObjectDescription):
|
|||
}
|
||||
|
||||
doc_field_types = [
|
||||
TypedField('parameter', label=l_('Parameters'),
|
||||
TypedField('parameter', label=_('Parameters'),
|
||||
names=('param', 'parameter', 'arg', 'argument'),
|
||||
typerolename='obj', typenames=('paramtype', 'type')),
|
||||
TypedField('variable', label=l_('Variables'), rolename='obj',
|
||||
TypedField('variable', label=_('Variables'), rolename='obj',
|
||||
names=('var', 'ivar', 'cvar'),
|
||||
typerolename='obj', typenames=('vartype',)),
|
||||
GroupedField('exceptions', label=l_('Raises'), rolename='exc',
|
||||
GroupedField('exceptions', label=_('Raises'), rolename='exc',
|
||||
names=('raises', 'raise', 'exception', 'except'),
|
||||
can_collapse=True),
|
||||
Field('returnvalue', label=l_('Returns'), has_arg=False,
|
||||
Field('returnvalue', label=_('Returns'), has_arg=False,
|
||||
names=('returns', 'return')),
|
||||
Field('returntype', label=l_('Return type'), has_arg=False,
|
||||
Field('returntype', label=_('Return type'), has_arg=False,
|
||||
names=('rtype',)),
|
||||
]
|
||||
|
||||
|
|
@ -493,8 +493,8 @@ class RubyModuleIndex(Index):
|
|||
"""
|
||||
|
||||
name = 'modindex'
|
||||
localname = l_('Ruby Module Index')
|
||||
shortname = l_('modules')
|
||||
localname = _('Ruby Module Index')
|
||||
shortname = _('modules')
|
||||
|
||||
def generate(self, docnames=None):
|
||||
content = {}
|
||||
|
|
@ -561,17 +561,17 @@ class RubyDomain(Domain):
|
|||
name = 'rb'
|
||||
label = 'Ruby'
|
||||
object_types = {
|
||||
'function': ObjType(l_('function'), 'func', 'obj'),
|
||||
'global': ObjType(l_('global variable'), 'global', 'obj'),
|
||||
'method': ObjType(l_('method'), 'meth', 'obj'),
|
||||
'class': ObjType(l_('class'), 'class', 'obj'),
|
||||
'exception': ObjType(l_('exception'), 'exc', 'obj'),
|
||||
'classmethod': ObjType(l_('class method'), 'meth', 'obj'),
|
||||
'attr_reader': ObjType(l_('attribute'), 'attr', 'obj'),
|
||||
'attr_writer': ObjType(l_('attribute'), 'attr', 'obj'),
|
||||
'attr_accessor': ObjType(l_('attribute'), 'attr', 'obj'),
|
||||
'const': ObjType(l_('const'), 'const', 'obj'),
|
||||
'module': ObjType(l_('module'), 'mod', 'obj'),
|
||||
'function': ObjType(_('function'), 'func', 'obj'),
|
||||
'global': ObjType(_('global variable'), 'global', 'obj'),
|
||||
'method': ObjType(_('method'), 'meth', 'obj'),
|
||||
'class': ObjType(_('class'), 'class', 'obj'),
|
||||
'exception': ObjType(_('exception'), 'exc', 'obj'),
|
||||
'classmethod': ObjType(_('class method'), 'meth', 'obj'),
|
||||
'attr_reader': ObjType(_('attribute'), 'attr', 'obj'),
|
||||
'attr_writer': ObjType(_('attribute'), 'attr', 'obj'),
|
||||
'attr_accessor': ObjType(_('attribute'), 'attr', 'obj'),
|
||||
'const': ObjType(_('const'), 'const', 'obj'),
|
||||
'module': ObjType(_('module'), 'mod', 'obj'),
|
||||
}
|
||||
|
||||
directives = {
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
--index-url https://pypi.python.org/simple
|
||||
setuptools>=20.10.0,<=57.4.0
|
||||
sphinx==1.5.6
|
||||
sphinx-bootstrap-theme==0.4.8
|
||||
docutils==0.16
|
||||
Jinja2==3.0.3
|
||||
setuptools==65.3.0
|
||||
sphinx==5.1.1
|
||||
sphinx-bootstrap-theme==0.8.1
|
||||
docutils==0.19
|
||||
Jinja2==3.1.2
|
||||
|
|
|
|||
|
|
@ -222,7 +222,7 @@ The FoundationDB client library performs most tasks on a singleton thread (which
|
|||
Future
|
||||
======
|
||||
|
||||
Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their result. These functions always return :type:`FDBFuture*`. An :type:`FDBFuture` object represents a result value or error to be delivered at some future time. You can wait for a Future to be "ready" -- to have a value or error delivered -- by setting a callback function, or by blocking a thread, or by polling. Once a Future is ready, you can extract either an error code or a value of the appropriate type (the documentation for the original function will tell you which :func:`fdb_future_get_*()` function you should call).
|
||||
Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their result. These functions always return ``FDBFuture*``. An :type:`FDBFuture` object represents a result value or error to be delivered at some future time. You can wait for a Future to be "ready" -- to have a value or error delivered -- by setting a callback function, or by blocking a thread, or by polling. Once a Future is ready, you can extract either an error code or a value of the appropriate type (the documentation for the original function will tell you which ``fdb_future_get_()`` function you should call).
|
||||
|
||||
To use the API in a synchronous way, you would typically do something like this for each asynchronous call::
|
||||
|
||||
|
|
@ -282,7 +282,7 @@ See :ref:`developer-guide-programming-with-futures` for further (language-indepe
|
|||
|
||||
.. type:: FDBCallback
|
||||
|
||||
A pointer to a function which takes :type:`FDBFuture*` and ``void*`` and returns ``void``.
|
||||
A pointer to a function which takes ``FDBFuture*`` and ``void*`` and returns ``void``.
|
||||
|
||||
.. function:: void fdb_future_release_memory(FDBFuture* future)
|
||||
|
||||
|
|
@ -298,13 +298,13 @@ See :ref:`developer-guide-programming-with-futures` for further (language-indepe
|
|||
|
||||
.. function:: fdb_error_t fdb_future_get_int64(FDBFuture* future, int64_t* out)
|
||||
|
||||
Extracts a 64-bit integer from an :type:`FDBFuture*` into a caller-provided variable of type ``int64_t``. |future-warning|
|
||||
Extracts a 64-bit integer from a pointer to :type:`FDBFuture` into a caller-provided variable of type ``int64_t``. |future-warning|
|
||||
|
||||
|future-get-return1| |future-get-return2|.
|
||||
|
||||
.. function:: fdb_error_t fdb_future_get_key_array( FDBFuture* f, FDBKey const** out_key_array, int* out_count)
|
||||
|
||||
Extracts an array of :type:`FDBKey` from an :type:`FDBFuture*` into a caller-provided variable of type ``FDBKey*``. The size of the array will also be extracted and passed back by a caller-provided variable of type ``int`` |future-warning|
|
||||
Extracts an array of :type:`FDBKey` from an ``FDBFuture*`` into a caller-provided variable of type ``FDBKey*``. The size of the array will also be extracted and passed back by a caller-provided variable of type ``int`` |future-warning|
|
||||
|
||||
|future-get-return1| |future-get-return2|.
|
||||
|
||||
|
|
@ -547,13 +547,13 @@ Applications must provide error handling and an appropriate retry loop around th
|
|||
|
||||
.. function:: void fdb_transaction_set_read_version(FDBTransaction* transaction, int64_t version)
|
||||
|
||||
Sets the snapshot read version used by a transaction. This is not needed in simple cases. If the given version is too old, subsequent reads will fail with error_code_transaction_too_old; if it is too new, subsequent reads may be delayed indefinitely and/or fail with error_code_future_version. If any of :func:`fdb_transaction_get_*()` have been called on this transaction already, the result is undefined.
|
||||
Sets the snapshot read version used by a transaction. This is not needed in simple cases. If the given version is too old, subsequent reads will fail with error_code_transaction_too_old; if it is too new, subsequent reads may be delayed indefinitely and/or fail with error_code_future_version. If any of ``fdb_transaction_get_*()`` have been called on this transaction already, the result is undefined.
|
||||
|
||||
.. function:: FDBFuture* fdb_transaction_get_read_version(FDBTransaction* transaction)
|
||||
|
||||
|future-return0| the transaction snapshot read version. |future-return1| call :func:`fdb_future_get_int64()` to extract the version into an int64_t that you provide, |future-return2|
|
||||
|
||||
The transaction obtains a snapshot read version automatically at the time of the first call to :func:`fdb_transaction_get_*()` (including this one) and (unless causal consistency has been deliberately compromised by transaction options) is guaranteed to represent all transactions which were reported committed before that call.
|
||||
The transaction obtains a snapshot read version automatically at the time of the first call to ``fdb_transaction_get_*()`` (including this one) and (unless causal consistency has been deliberately compromised by transaction options) is guaranteed to represent all transactions which were reported committed before that call.
|
||||
|
||||
.. function:: FDBFuture* fdb_transaction_get(FDBTransaction* transaction, uint8_t const* key_name, int key_name_length, fdb_bool_t snapshot)
|
||||
|
||||
|
|
@ -829,7 +829,7 @@ Applications must provide error handling and an appropriate retry loop around th
|
|||
|
||||
|future-returnvoid|
|
||||
|
||||
Callers will usually want to retry a transaction if the commit or a prior :func:`fdb_transaction_get_*()` returns a retryable error (see :func:`fdb_transaction_on_error()`).
|
||||
Callers will usually want to retry a transaction if the commit or a prior ``fdb_transaction_get_*()`` returns a retryable error (see :func:`fdb_transaction_on_error()`).
|
||||
|
||||
|commit-unknown-result-blurb|
|
||||
|
||||
|
|
@ -878,9 +878,9 @@ Applications must provide error handling and an appropriate retry loop around th
|
|||
|
||||
.. function:: FDBFuture* fdb_transaction_on_error(FDBTransaction* transaction, fdb_error_t error)
|
||||
|
||||
Implements the recommended retry and backoff behavior for a transaction. This function knows which of the error codes generated by other :func:`fdb_transaction_*()` functions represent temporary error conditions and which represent application errors that should be handled by the application. It also implements an exponential backoff strategy to avoid swamping the database cluster with excessive retries when there is a high level of conflict between transactions.
|
||||
Implements the recommended retry and backoff behavior for a transaction. This function knows which of the error codes generated by other ``fdb_transaction_*()`` functions represent temporary error conditions and which represent application errors that should be handled by the application. It also implements an exponential backoff strategy to avoid swamping the database cluster with excessive retries when there is a high level of conflict between transactions.
|
||||
|
||||
On receiving any type of error from an :func:`fdb_transaction_*()` function, the application should:
|
||||
On receiving any type of error from an ``fdb_transaction_*()`` function, the application should:
|
||||
|
||||
1. Call :func:`fdb_transaction_on_error()` with the returned :type:`fdb_error_t` code.
|
||||
|
||||
|
|
@ -963,15 +963,15 @@ Key selectors
|
|||
|
||||
In the FoundationDB C API, key selectors are not represented by a structure of any kind, but are instead expressed as sequential parameters to |get-key-func| and |get-range-func|. For convenience, the most common key selectors are available as C macros that expand to the appropriate parameters.
|
||||
|
||||
.. function:: FDB_KEYSEL_LAST_LESS_THAN(key_name, key_name_length)
|
||||
.. type:: FDB_KEYSEL_LAST_LESS_THAN(key_name, key_name_length)
|
||||
|
||||
.. function:: FDB_KEYSEL_LAST_LESS_OR_EQUAL(key_name, key_name_length)
|
||||
.. type:: FDB_KEYSEL_LAST_LESS_OR_EQUAL(key_name, key_name_length)
|
||||
|
||||
.. function:: FDB_KEYSEL_FIRST_GREATER_THAN(key_name, key_name_length)
|
||||
.. type:: FDB_KEYSEL_FIRST_GREATER_THAN(key_name, key_name_length)
|
||||
|
||||
.. function:: FDB_KEYSEL_FIRST_GREATER_OR_EQUAL(key_name, key_name_length)
|
||||
.. type:: FDB_KEYSEL_FIRST_GREATER_OR_EQUAL(key_name, key_name_length)
|
||||
|
||||
To use one of these macros, simply replace the four parameters in the function with one of :func:`FDB_KEYSEL_*`::
|
||||
To use one of these macros, simply replace the four parameters in the function with one of ``FDB_KEYSEL_*``::
|
||||
|
||||
future = fdb_transaction_get_key(transaction, "key", 3, 0, 2, 0);
|
||||
|
||||
|
|
|
|||
|
|
@ -194,10 +194,6 @@ After importing the ``fdb`` module and selecting an API version, you probably wa
|
|||
|
||||
|option-tls-key-bytes|
|
||||
|
||||
.. method :: fdb.options.set_tls_verify_peers(verification_pattern)
|
||||
|
||||
|option-tls-verify-peers|
|
||||
|
||||
.. method :: fdb.options.set_tls_ca_bytes(ca_bundle)
|
||||
|
||||
|option-tls-ca-bytes|
|
||||
|
|
@ -210,10 +206,6 @@ After importing the ``fdb`` module and selecting an API version, you probably wa
|
|||
|
||||
|option-tls-password|
|
||||
|
||||
.. method :: fdb.options.set_disable_multi_version_client_api()
|
||||
|
||||
|option-disable-multi-version-client-api|
|
||||
|
||||
.. method :: fdb.options.set_disable_local_client()
|
||||
|
||||
|option-set-disable-local-client|
|
||||
|
|
@ -761,10 +753,6 @@ In each of the methods below, ``param`` should be a string appropriately packed
|
|||
Committing
|
||||
----------
|
||||
|
||||
.. decorator:: transactional()
|
||||
|
||||
The ``transactional`` decorator makes it easy to write transactional functions which accept a :class:`Database`, :class`Tenant`, or :class:`Transaction` as a parameter and automatically commit. See :func:`@fdb.transactional <transactional>` for explanation and examples.
|
||||
|
||||
.. method :: Transaction.commit()
|
||||
|
||||
Attempt to commit the changes made in the transaction to the database. Returns a :class:`FutureVoid` representing the asynchronous result of the commit. You **must** call the :meth:`Future.wait()` method on the returned :class:`FutureVoid`, which will raise an exception if the commit failed.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
.. default-domain:: py
|
||||
.. default-domain:: py
|
||||
.. highlight:: python
|
||||
.. module:: fdb
|
||||
|
||||
.. Required substitutions for api-common.rst.inc
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
.. default-domain:: py
|
||||
.. default-domain:: py
|
||||
.. highlight:: python
|
||||
.. module:: fdb
|
||||
|
||||
.. Required substitutions for api-common.rst.inc
|
||||
|
||||
|
|
|
|||
|
|
@ -50,6 +50,7 @@ The latest changes are detailed in :ref:`release-notes`. The documentation has t
|
|||
:hidden:
|
||||
|
||||
local-dev
|
||||
internal-dev-tools
|
||||
why-foundationdb
|
||||
technical-overview
|
||||
client-design
|
||||
|
|
|
|||
|
|
@ -0,0 +1,58 @@
|
|||
##################
|
||||
Internal Dev Tools
|
||||
##################
|
||||
|
||||
Code Probes
|
||||
===========
|
||||
|
||||
Code probes are a mechanism in FDB to prove that certain code-paths are being tested under the right conditions. They differ from code coverage in multiple ways (explained below).
|
||||
|
||||
The general format of a code probe is:
|
||||
|
||||
.. code-block:: C++
|
||||
|
||||
CODE_PROBE(<condition>, "Comment", [annotations...]);
|
||||
|
||||
A simple example of a code probe could look as follows:
|
||||
|
||||
.. code-block:: C++
|
||||
|
||||
CODE_PROBE(self->forceRecovery, "Resolver detects forced recovery", context::sim2);
|
||||
|
||||
On a very high level, the above code will indicate that whenever this line is executed and ``self->forceRecovery`` is ``true``, we ran into some interesting case. In addition this probe is also annotated with ``context::sim2``. This indicates that we expect this code to be eventually hit in simulation.
|
||||
|
||||
By default, FDB simply will write a trace-line when this code is hit and the condition is ``true``. If the code is never hit, the simulator will, at the end of the run, print the code probe but set the ``covered`` field to ``false``.
|
||||
|
||||
We expect that ALL code probes will be hit in a nightly run. In the future we can potentially use this feature for other things (like instructing the simulator to do an extensive search starting when one of these probes is being hit).
|
||||
|
||||
In addition to ``context`` annotations, users can also define and pass assertsions. For example:
|
||||
|
||||
.. code-block:: C++
|
||||
|
||||
CODE_PROBE(condition, "Some comment", assert::simOnly);
|
||||
|
||||
These will add an assertion to the code. In addition to that, the simulator will not print missed code probes that asserted that the probe won't be hit in simulation.
|
||||
|
||||
Test Harness
|
||||
============
|
||||
|
||||
TestHarness is our primary testing tool. It has multiple jobs:
|
||||
|
||||
* *Running*: It can run a test in Joshua.
|
||||
* *Statictics*: It will chose a test to run based on previously spent CPU time for all tests. It does that by writing statistics about the test at the end of each run.
|
||||
* *Reporting*: After an ensemble has finished (or while it is running), ``TestHarness`` can be used to generate a report in ``xml`` or ``json``.
|
||||
|
||||
Test Harness can be found in the FDB source repository under ``contrib/TestHarness2``. It has a weak dependency to `joshua <https://github.com/foundationDB/fdb-joshua>`_ (if Test Harness can find joshua it will report back about failed tests, otherwise it will just print out general statistics about the ensemble). Joshua will call Test Harness as follows:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python3 -m test_harness.app -s ${JOSHUA_SEED} --old-binaries-path ${OLDBINDIR}
|
||||
|
||||
Here the seed is a random number generated by joshua and ``OLDBINDIR`` is a directory path where the old fdb binaries can be found (this is needed for restart tests). If once wants to retry a test they can pass the previous joshua seed, a directory path that has *exactly* the same content as ``OLDBINARYDIR``, plus the reported statistics to the test harness app. This should then rerun the same code as before.
|
||||
|
||||
In order to figure out what command line arguments ``test_harness.app`` (and ``test_harness.results``) accepts, one can check the contents of ``contrib/TestHarness2/test_harness/config.py``.
|
||||
|
||||
Reporting
|
||||
---------
|
||||
|
||||
After a joshua ensemble completed, ``test_harness.results`` can be used in order to get a report on the ensemble. This will include, by default, a list of all failed tests (similar to ``joshua tail --errors``, though in a more human readable file). For completed ensemble it will also print code probes that weren't hit often enough. An ensemble is considered to be successful if no simulation runs completed with an error AND all code probes have been hit sufficiently often.
|
||||
Loading…
Reference in New Issue