CODING_STYLE: split out section about runtime behaviour
This commit is contained in:
parent
78e5b4d7ee
commit
4467d39315
|
@ -60,10 +60,6 @@ title: Coding Style
|
||||||
- Please name structures in `PascalCase` (with exceptions, such as public API
|
- Please name structures in `PascalCase` (with exceptions, such as public API
|
||||||
structs), variables and functions in `snake_case`.
|
structs), variables and functions in `snake_case`.
|
||||||
|
|
||||||
- Be exceptionally careful when formatting and parsing floating point
|
|
||||||
numbers. Their syntax is locale dependent (i.e. `5.000` in en_US is
|
|
||||||
generally understood as 5, while in de_DE as 5000.).
|
|
||||||
|
|
||||||
- Avoid static variables, except for caches and very few other
|
- Avoid static variables, except for caches and very few other
|
||||||
cases. Think about thread-safety! While most of our code is never
|
cases. Think about thread-safety! While most of our code is never
|
||||||
used in threaded environments, at least the library code should make
|
used in threaded environments, at least the library code should make
|
||||||
|
@ -89,16 +85,6 @@ title: Coding Style
|
||||||
Furthermore, in all three groups, order all includes alphabetically
|
Furthermore, in all three groups, order all includes alphabetically
|
||||||
so duplicate includes can easily be detected.
|
so duplicate includes can easily be detected.
|
||||||
|
|
||||||
- Avoid leaving long-running child processes around, i.e. `fork()`s that
|
|
||||||
are not followed quickly by an `execv()` in the child. Resource
|
|
||||||
management is unclear in this case, and memory CoW will result in
|
|
||||||
unexpected penalties in the parent much, much later on.
|
|
||||||
|
|
||||||
- Don't block execution for arbitrary amounts of time using `usleep()`
|
|
||||||
or a similar call, unless you really know what you do. Just "giving
|
|
||||||
something some time", or so is a lazy excuse. Always wait for the
|
|
||||||
proper event, instead of doing time-based poll loops.
|
|
||||||
|
|
||||||
- Please avoid using global variables as much as you can. And if you
|
- Please avoid using global variables as much as you can. And if you
|
||||||
do use them make sure they are static at least, instead of
|
do use them make sure they are static at least, instead of
|
||||||
exported. Especially in library-like code it is important to avoid
|
exported. Especially in library-like code it is important to avoid
|
||||||
|
@ -118,13 +104,6 @@ title: Coding Style
|
||||||
global variables, for example data parsed from command lines, see
|
global variables, for example data parsed from command lines, see
|
||||||
below.
|
below.
|
||||||
|
|
||||||
- Make sure to enforce limits on every user controllable resource. If the user
|
|
||||||
can allocate resources in your code, your code must enforce some form of
|
|
||||||
limits after which it will refuse operation. It's fine if it is hard-coded (at
|
|
||||||
least initially), but it needs to be there. This is particularly important
|
|
||||||
for objects that unprivileged users may allocate, but also matters for
|
|
||||||
everything else any user may allocated.
|
|
||||||
|
|
||||||
- You might wonder what kind of common code belongs in `src/shared/` and what
|
- You might wonder what kind of common code belongs in `src/shared/` and what
|
||||||
belongs in `src/basic/`. The split is like this: anything that is used to
|
belongs in `src/basic/`. The split is like this: anything that is used to
|
||||||
implement the public shared object we provide (sd-bus, sd-login, sd-id128,
|
implement the public shared object we provide (sd-bus, sd-login, sd-id128,
|
||||||
|
@ -156,16 +135,6 @@ title: Coding Style
|
||||||
aren't, we are happy to use GNU or Linux APIs, and expect non-GNU
|
aren't, we are happy to use GNU or Linux APIs, and expect non-GNU
|
||||||
implementations of libc to catch up with glibc.
|
implementations of libc to catch up with glibc.
|
||||||
|
|
||||||
- Whenever installing a signal handler, make sure to set `SA_RESTART` for it, so
|
|
||||||
that interrupted system calls are automatically restarted, and we minimize
|
|
||||||
hassles with handling `EINTR` (in particular as `EINTR` handling is pretty broken
|
|
||||||
on Linux).
|
|
||||||
|
|
||||||
- When applying C-style unescaping as well as specifier expansion on the same
|
|
||||||
string, always apply the C-style unescaping fist, followed by the specifier
|
|
||||||
expansion. When doing the reverse, make sure to escape `%` in specifier-style
|
|
||||||
first (i.e. `%` → `%%`), and then do C-style escaping where necessary.
|
|
||||||
|
|
||||||
## Using C Constructs
|
## Using C Constructs
|
||||||
|
|
||||||
- Preferably allocate local variables on the top of the block:
|
- Preferably allocate local variables on the top of the block:
|
||||||
|
@ -374,6 +343,39 @@ title: Coding Style
|
||||||
matters particularly in inner loops (but note that `strjoina()` cannot be
|
matters particularly in inner loops (but note that `strjoina()` cannot be
|
||||||
used there).
|
used there).
|
||||||
|
|
||||||
|
## Runtime Behaviour
|
||||||
|
|
||||||
|
- Avoid leaving long-running child processes around, i.e. `fork()`s that are
|
||||||
|
not followed quickly by an `execv()` in the child. Resource management is
|
||||||
|
unclear in this case, and memory CoW will result in unexpected penalties in
|
||||||
|
the parent much, much later on.
|
||||||
|
|
||||||
|
- Don't block execution for arbitrary amounts of time using `usleep()` or a
|
||||||
|
similar call, unless you really know what you do. Just "giving something some
|
||||||
|
time", or so is a lazy excuse. Always wait for the proper event, instead of
|
||||||
|
doing time-based poll loops.
|
||||||
|
|
||||||
|
- Whenever installing a signal handler, make sure to set `SA_RESTART` for it,
|
||||||
|
so that interrupted system calls are automatically restarted, and we minimize
|
||||||
|
hassles with handling `EINTR` (in particular as `EINTR` handling is pretty
|
||||||
|
broken on Linux).
|
||||||
|
|
||||||
|
- When applying C-style unescaping as well as specifier expansion on the same
|
||||||
|
string, always apply the C-style unescaping fist, followed by the specifier
|
||||||
|
expansion. When doing the reverse, make sure to escape `%` in specifier-style
|
||||||
|
first (i.e. `%` → `%%`), and then do C-style escaping where necessary.
|
||||||
|
|
||||||
|
- Be exceptionally careful when formatting and parsing floating point
|
||||||
|
numbers. Their syntax is locale dependent (i.e. `5.000` in en_US is generally
|
||||||
|
understood as 5, while in de_DE as 5000.).
|
||||||
|
|
||||||
|
- Make sure to enforce limits on every user controllable resource. If the user
|
||||||
|
can allocate resources in your code, your code must enforce some form of
|
||||||
|
limits after which it will refuse operation. It's fine if it is hard-coded
|
||||||
|
(at least initially), but it needs to be there. This is particularly
|
||||||
|
important for objects that unprivileged users may allocate, but also matters
|
||||||
|
for everything else any user may allocated.
|
||||||
|
|
||||||
## Types
|
## Types
|
||||||
|
|
||||||
- Think about the types you use. If a value cannot sensibly be negative, do not
|
- Think about the types you use. If a value cannot sensibly be negative, do not
|
||||||
|
|
Loading…
Reference in a new issue