From 4467d39315f1ca2470dde117e7828b261e1ad948 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 12 Apr 2019 16:58:46 +0200 Subject: CODING_STYLE: split out section about runtime behaviour --- docs/CODING_STYLE.md | 64 +++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md index cb256c8447..9b2fd5cc84 100644 --- a/docs/CODING_STYLE.md +++ b/docs/CODING_STYLE.md @@ -60,10 +60,6 @@ title: Coding Style - Please name structures in `PascalCase` (with exceptions, such as public API 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 cases. Think about thread-safety! While most of our code is never 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 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 do use them make sure they are static at least, instead of 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 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 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, @@ -156,16 +135,6 @@ title: Coding Style aren't, we are happy to use GNU or Linux APIs, and expect non-GNU 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 - 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 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 - Think about the types you use. If a value cannot sensibly be negative, do not -- cgit v1.2.1