0
0
Fork 0
mirror of https://github.com/matrix-construct/construct synced 2024-11-21 17:31:21 +01:00

Various updates; remove unnecessary sections.

Jason Volk 2020-07-08 10:12:41 -07:00
parent 5a9c31c24f
commit 535e84357c

@ -258,13 +258,6 @@ other words, if you have a prototype like `foo(const std::string &message)` you
OTOH, if you have `foo(const options &options, const std::string &message)` one should skip
the name for `options &` as it just adds redundant text to the prototype.
* Consider any code inside a runtime `assert()` statement to **entirely**
disappear in optimized builds. If some implementations of `assert()` may only
elide the boolean check and thus preserve the inner statement and the effects
of its execution: this is not standard; we do not rely on this. Do not use
`assert()` to check return values of statements that need to be executed in
optimized builds.
#### Comments
@ -320,7 +313,7 @@ line starting with `//` with no text after it. Combined with the allowed
completely blank line after that you now have more whitespace.
### Conventions
## Conventions
These are things you should know when mulling over the code as a whole. Knowing
these things will help you avoid various gotchas and not waste your tim
@ -354,32 +347,6 @@ which count characters printed *not including null*. They may return a
`string_view`/`const_buffer` of that size (never viewing the null).
#### Iteration protocols
When not using STL-iterators, you may encounter some closure/callback-based
iterator functions. Usually that's a `for_each()`. If we want to break out
of the loop, our conventions are as follows:
- *find protocol* for `find()` functions. The closure returns true to break
the loop at that element, false to continue. The `find()` function itself
then returns a pointer or reference to that element. If the end of the
iteration is reached then a `find()` usually returns `nullptr` or throws an
exception, etc.
- *test protocol* for `test()` functions (this has nothing to do with unit-
tests or development testing). This is the same logic as the find protocol
except the `test()` function itself returns true if the closure broke the
loop by returning true, or false if the end of the iteration was reached.
- *until protocol* for `until()` functions. The closure "remains true 'till
the end." When the end is reached, true is returned. The closure returns false
to break the loop, and then false is returned from until() as well.
Overloads of `for_each()` may be encountered accepting closures that return
`void` and others that return `bool`. The `bool` overloads use the
*until protocol* as that matches the same logic in a `for(; bool;)` loop.
#### nothrow is not noexcept
Often a function is overloaded with an std::nothrow_t argument or our
@ -388,26 +355,17 @@ a specific exception expected from the overload alternative** (or set of
exceptions, etc). Any exception may still come out of that nothrow overload;
technically including the specific exception if it came from somewhere else!
Use the noexcept keyword with tact, not by default. Most of the project
propagates exceptions. Functions that handle their errors and are expected to
return (i.e since they catch `std::exception`), still throw special exceptions
like `ircd::ctx::terminated`. If the `catch(...)` and `noexcept` features are
used: developers must cooperate by handling ctx interruptions and propagating
terminations. This is not an issue on leaf and simple functions where we tend
to make use of `noexcept`, especially for non-inlines allowing for better
compiler optimizations to occur.
The `noexcept` specifier is employed to mark non-inline functions which don't
throw; we elide `noexcept` for inline functions which don't throw unless there
is an explicit reason for it. The former provides valuable information to the
compiler affecting optimization around calls where the compiler can't see
the callee's implementation to deduce it doesn't throw.
#### Indications of yielding and IO's
There is a section on how yielding and IO can occur far up the stack from a
benign-looking callsite in ctx/README. We try to make comments to indicate
these things directly in the definitions and certainly in documentation.
Some of those indications may say nothing more than `[GET]` and `[SET]` without
any other comment. That is the minimum acceptable marking for something which
will likely do read or write IO respectively to disk or even the network. In
any such case the ircd::ctx will definitely yield if that happens.
Most of the project propagates exceptions. Functions that handle their errors
and are expected to return (i.e since they catch `std::exception`), still throw
special exceptions like `ircd::ctx::terminated`. If the `catch(...)` and
`noexcept` features are used: developers must cooperate by handling ctx
interruptions and propagating terminations.
#### Nothing ticks