diff --git a/.github/Guidelines/Coding.md b/.github/Guidelines/Coding.md index 94f7cfb5..dbd9f681 100644 --- a/.github/Guidelines/Coding.md +++ b/.github/Guidelines/Coding.md @@ -84,7 +84,24 @@ When `VlppParser2` is available to the current project, complex parsers always r - Prefer the latest C++ features (up to C++ 20). - Prefer template variadic arguments, over hard-coded-counting solutions. -## Advanced C++ Coding Rules for Reflectable Types +### for Thread Safe Programming + +- Most of the code do not require thread safety, DO NOT over engineering. +- `SpinLock` is only for protecting a piece of code or data in a super flashy short time. + - When defining a `SpinLock` field, names it begins with `lock`, a `// covers a, b, c` comment is recommended to put above it, a empty line is recommended to put around it. + - When doing `read-process-write` but the `write` part doesn't depend on the result of `process`: + - The below rules only involve when `process` is heavy, if anything is simple, keep it simple. + - You can copy or move the heavy structure in `SPIN_LOCK`, and `process` after `SPIN_LOCK`. + - Especially for scenario when a container should be processed and cleared, `std::move` would be the best choice to copy and clean `Vlpp` containers. Using moved `Vlpp` containers is not undefined behavior. +- When using other locks, try your best to only use methods that available to all platforms. + - Write cross platform code when it is performance optimal for all platforms. + - If Windows specific methods could make Windows implementation much better, then you are allowed to implement them in different ways. + - Use `lock` (both `SpinLock` and `CriticalSection`), `mutex`, `semaphore`, `event`, `semaphore`, `rwlock`, `cv` as lock variable prefixes. +- Prefer lock free construction only when the code would be simple, DO NOT involve complex lock free trick unless explicitly required. +- `std::atomic` should be considered and use it precisely. The code should be correct when running parallelly while I don't want unnecessary `std::atomic`. + - `atomic_vint` is widely used in the library, use it for `vint`. + +### for Reflectable Types - Any interface or class `X` should inherit from `vl::reflection::Description`. - If such a class (not including interface) should be inheritable in Workflow script, use `AggregatableDescription` instead of `Description`.