From 161ed8a6909758dd3b194f4ca34dd2dfb8d07a38 Mon Sep 17 00:00:00 2001 From: David Lamparter Date: Wed, 22 Sep 2021 11:59:08 +0200 Subject: [PATCH] doc/workflow: prefer typesafe containers The typesafe containers have been around for quite a while now and haven't gone up in a blaze of flames, so let's add a "strong recommendation" to use them for new code and refactors. For the nhrpd custom lists I'm already working to remove them; meanwhile the old skiplists are primarily used in RFAPI (4 users outside of that), so those could be next. What remains are the old `list_*` and `hash_*`, which have >300 and >100 users respectively, making them a much harder problem to tackle. And the new hash implementation doesn't have the same level of debug/introspection yet (it's on my TODO.) Signed-off-by: David Lamparter --- doc/developer/workflow.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index c703be62fc..2ce5f5d1c8 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -637,6 +637,39 @@ well as CERT or MISRA C guidelines may provide useful input on safe C code. However, these rules are not applied as-is; some of them expressly collide with established practice. + +Container implementations +^^^^^^^^^^^^^^^^^^^^^^^^^ + +In particular to gain defensive coding benefits from better compiler type +checks, there is a set of replacement container data structures to be found +in :file:`lib/typesafe.h`. They're documented under :ref:`lists`. + +Unfortunately, the FRR codebase is quite large, and migrating existing code to +use these new structures is a tedious and far-reaching process (even if it +can be automated with coccinelle, the patches would touch whole swaths of code +and create tons of merge conflicts for ongoing work.) Therefore, little +existing code has been migrated. + +However, both **new code and refactors of existing code should use the new +containers**. If there are any reasons this can't be done, please work to +remove these reasons (e.g. by adding necessary features to the new containers) +rather than falling back to the old code. + +In order of likelyhood of removal, these are the old containers: + +- :file:`nhrpd/list.*`, ``hlist_*`` ⇒ ``DECLARE_LIST`` +- :file:`nhrpd/list.*`, ``list_*`` ⇒ ``DECLARE_DLIST`` +- :file:`lib/skiplist.*`, ``skiplist_*`` ⇒ ``DECLARE_SKIPLIST`` +- :file:`lib/*_queue.h` (BSD), ``SLIST_*`` ⇒ ``DECLARE_LIST`` +- :file:`lib/*_queue.h` (BSD), ``LIST_*`` ⇒ ``DECLARE_DLIST`` +- :file:`lib/*_queue.h` (BSD), ``STAILQ_*`` ⇒ ``DECLARE_LIST`` +- :file:`lib/*_queue.h` (BSD), ``TAILQ_*`` ⇒ ``DECLARE_DLIST`` +- :file:`lib/hash.*`, ``hash_*`` ⇒ ``DECLARE_HASH`` +- :file:`lib/linklist.*`, ``list_*`` ⇒ ``DECLARE_DLIST`` +- open-coded linked lists ⇒ ``DECLARE_LIST``/``DECLARE_DLIST`` + + Code Formatting ---------------