From c03415caf1e09310e958c7277bfc276ed3e4c309 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Tue, 15 Dec 2020 17:50:35 +0800 Subject: [PATCH] doc/dev/crimson: quote inline codeblock using "``" backquote is used for quoting italic typed text. Signed-off-by: Kefu Chai --- doc/dev/crimson/error-handling.rst | 42 +++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/dev/crimson/error-handling.rst b/doc/dev/crimson/error-handling.rst index ee241d9589144..43017457df1cb 100644 --- a/doc/dev/crimson/error-handling.rst +++ b/doc/dev/crimson/error-handling.rst @@ -3,16 +3,16 @@ error handling ============== -In Seastar, a `future` represents a value not yet available but that can become -available later. `future` can have one of following states: +In Seastar, a ``future`` represents a value not yet available but that can become +available later. ``future`` can have one of following states: * unavailable: value is not available yet, * value, * failed: an exception was thrown when computing the value. This exception has - been captured and stored in the `future` instance via `std::exception_ptr`. + been captured and stored in the ``future`` instance via ``std::exception_ptr``. -In the last case, the exception can be processed using `future::handle_exception()` or -`future::handle_exception_type()`. Seastar even provides `future::or_terminate()` to +In the last case, the exception can be processed using ``future::handle_exception()`` or +``future::handle_exception_type()``. Seastar even provides ``future::or_terminate()`` to terminate the program if the future fails. But in Crimson, quite a few errors are not serious enough to fail the program entirely. @@ -26,19 +26,19 @@ that all expected errors are handled. It should be something like the statical a performed by compiler to spit a warning if any enum value is not handled in a ``switch-case`` statement. -Unfortunately, `seastar::future` is not able to satisfy these two requirements. +Unfortunately, ``seastar::future`` is not able to satisfy these two requirements. * Seastar imposes re-throwing an exception to dispatch between different types of exceptions. This is not very performant nor even scalable as locking in the language's runtime can occur. * Seastar does not encode the expected exception type in the type of the returned - `seastar::future`. Only the type of the value is encoded. This imposes huge + ``seastar::future``. Only the type of the value is encoded. This imposes huge mental load on programmers as ensuring that all intended errors are indeed handled requires manual code audit. .. highlight:: c++ -So, "errorator" is created. It is a wrapper around the vanilla `seastar::future`. +So, "errorator" is created. It is a wrapper around the vanilla ``seastar::future``. It addresses the performance and scalability issues while embedding the information about all expected types-of-errors to the type-of-future.:: @@ -47,14 +47,14 @@ about all expected types-of-errors to the type-of-future.:: In above example we defined an errorator that allows for two error types: -* `crimson::ct_error::enoent` and -* `crimson::ct_error::einval`. +* ``crimson::ct_error::enoent`` and +* ``crimson::ct_error::einval``. -These (and other ones in the `crimson::ct_error` namespace) are basically -unthrowable wrappers over `std::error_code` to exclude accidental throwing +These (and other ones in the ``crimson::ct_error`` namespace) are basically +unthrowable wrappers over ``std::error_code`` to exclude accidental throwing and ensure signaling errors in a way that enables compile-time checking. -The most fundamental thing in an errorator is a descendant of `seastar::future` +The most fundamental thing in an errorator is a descendant of ``seastar::future`` which can be used as e.g. function's return type:: static ertr::future foo(int bar) { @@ -80,9 +80,9 @@ would result in a compile-time error:: The errorator concept goes further. It not only provides callers with the information about all potential errors embedded in the function's type; it also ensures at the caller site that all these errors are handled. As the reader probably know, the main method -in `seastar::future` is `then()`. On errorated future it is available but only if errorator's -error set is empty (literally: `errorator<>::future`); otherwise callers have -to use `safe_then()` instead:: +in ``seastar::future`` is ``then()``. On errorated future it is available but only if errorator's +error set is empty (literally: ``errorator<>::future``); otherwise callers have +to use ``safe_then()`` instead:: seastar::future<> baz() { return foo(42).safe_then( @@ -102,10 +102,10 @@ to use `safe_then()` instead:: }); } -In the above example `ertr::all_same_way` has been used to handle all errors in the same +In the above example ``ertr::all_same_way`` has been used to handle all errors in the same manner. This is not obligatory -- a caller can handle each of them separately. Moreover, it can provide a handler for only a subset of errors. The price for that is the availability -of `then()`:: +of ``then()``:: using einval_ertr = crimson::errorator; @@ -129,8 +129,8 @@ of `then()`:: } That is, handling errors removes them from errorated future's error set. This works -in the opposite direction too -- returning new errors in `safe_then()` appends them -the error set. Of course, this set must be compliant with error set in the `baz()`'s +in the opposite direction too -- returning new errors in ``safe_then()`` appends them +the error set. Of course, this set must be compliant with error set in the ``baz()``'s signature:: using broader_ertr = crimson::errorator throw/catch-free, -- 2.39.5