diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index a5dee8881fec76..c43d780c0f2a60 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -41,6 +41,9 @@ AFL AIDL algs alloc +allocator +allocators +Ambrose Ameba amebad amebaiot @@ -317,6 +320,7 @@ cryptographic CSA csg csrrequest +cstdint csu csv ctl @@ -440,6 +444,7 @@ DNSStubListener docbuild Dockerfile Dockerfiles +docstrings Don'ts DoorLock DoorState @@ -565,6 +570,8 @@ FlowMeasurement FluorideConcentrationMeasurement focusable forkpty +formatter +formatters FOTA FreeRTOS FreeRTOSConfig @@ -731,6 +738,7 @@ IPython ISCAN isHexString isLowerCase +isort isUpperCase itemName iterable @@ -878,6 +886,7 @@ MediaPlayback MediaTek MEI mem +memcpy memdf MemMonitoring menuconfig @@ -933,6 +942,7 @@ mv MX mydir MyPASSWORD +mypy MySSID NAMESERVER NAMESPACE @@ -1442,6 +1452,7 @@ toJson tokenization tokenized tokenizer +toml toolchain toolchains topologies diff --git a/docs/style/CODING_STYLE_GUIDE.md b/docs/style/CODING_STYLE_GUIDE.md new file mode 100644 index 00000000000000..bba6ef4ffadbf5 --- /dev/null +++ b/docs/style/CODING_STYLE_GUIDE.md @@ -0,0 +1,172 @@ +# Coding Style Guide + +_Revision 6_ _2024-10-28_ + +This guide provides a small set of code guidelines used in the SDK. This guide +reflects the currently accepted style practices for the SDK and is subject to +change. + +The SDK was seeded from multiple different projects and contains contributions +from many different companies and the SDK code therefore uses several different +coding styles throughout the code base. Stylistically, code should attempt to +conform to the dominant style of the code being modified, while also adhering to +the guidelines below. + +## Language standard + +Code in the SDK conforms to the following standards. Changes to the C++ standard +happen relatively infrequently. Changes to the Python version are more frequent. + +| Language | Version | +| -------- | ------- | +| C++ | C++17 | +| Python | 3.10 | + +Product-specific software may elect to use later standards in their own work. + +## Coding Guidelines + +### Common + +#### When in Rome + +The most important convention and practice in the Matter SDK repo is "_When in +Rome..._", per the quote below. + +[quote, St. Ambrose] + +--- + +If you should be in Rome, live in the Roman manner; if you should be elsewhere, +live as they do there. + +--- + +Your extensions or fixes to existing code should match the prevailing style of +the original code. + +If you find the conventions so foreign or otherwise confusing, it may be best to +let whoever owns the file make the necessary changes or seek the counsel of +others in the group to find out what the right thing to do is. Never just start +changing code wholesale for personal reasons without consulting others first. + +#### Commenting Out or Disabling Code + +Unused code shall not be disabled by commenting it out with C- or C++-style +comments or with preprocessor `#if 0 ... #endif` semantics. Unused code should +be removed. + +#### Auto-formatters + +We use the following auto-formatters on code: + +| Language | Formatter | Style File | +| ----------- | ------------------ | ------------------------------------------------------------------------------------------ | +| C++ | clang-format | [.clang-format](https://github.com/project-chip/connectedhomeip/blob/master/.clang-format) | +| Objective-C | clang-format | [.clang-format](https://github.com/project-chip/connectedhomeip/blob/master/.clang-format) | +| java | google-java-format | N/A | +| Python | pep8, isort, ruff | [.restyled.yaml][restyle_link] (command line), [isort][isort_link], [ruff][ruff_link] | +| YAML | prettier | None | +| JSON | prettier | None | +| markdown | prettier | None | + +[restyle_link]: + https://github.com/project-chip/connectedhomeip/blob/master/.restyled.yaml +[isort_link]: + https://github.com/project-chip/connectedhomeip/blob/master/.isort.cfg +[ruff_link]: + https://github.com/project-chip/connectedhomeip/blob/master/ruff.toml + +All pull requests run formatting checks using these tools before merge is +allowed. Generated code is not run through restyle. + +### C++ + +#### Use C++ _cstdint_ for Plain Old Data Types + +Standard, scalar data types defined in _cstdint_ should be used for basic signed +and unsigned integer types, especially when size and serialization to +non-volatile storage or across a network is concerned. + +Examples of these are: `uint8_t`, `int8_t`, etc. + +#### Avoid top-level `using namespace` Statements in Headers + +By doing this, you are effectively forcing every other module that includes the +header to also be using the namespace. This causes namespace pollution and +generally defeats the purposes of namespaces. Fully-qualified symbols or +namespace blocks should be used instead. + +#### Classes / objects not exposed in a header should be in an anonymous namespace + +If a cpp class defines a class or instantiates a static object, it should be +enclosed in an anonymous namespace. + +``` +namespace { + // CPP internal defines go here +} // namespace +``` + +#### Singleton use + +The decision to use a singleton class should be considered with care. Do not +default to using a singleton for ease of writing code. + +If the class truly should be a singleton (ex. if it is controlling access to a +hardware resource) + +- The standard function name for accessing an SDK singleton is GetInstance(). +- Singleton classes should delete copy and move constructors + +#### Avoid Heap-based Resource Allocation and auto-resizing std containers + +Heap-based resource allocation should be avoided in the core SDK for common code +that may run on constrained embedded devices. This includes any container +element in std that automatically re-sizes itself at runtime (ex. vector, string +etc.) as these re-size operations are often large and can lead to memory +exhaustion and fragmentation on embedded systems. + +Heap-based allocation is allowed for controller code and is at the discretion of +platform vendors for platform-specific code. + +##### Alternatives + +In either case, recommended resource allocation alternatives are: + +- In-place allocation and initialization +- Pool-based allocators +- Platform-defined and -assigned allocators + +[CHIPMem.h](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/CHIPMem.h) +provides support for platform defined allocators. + +[Pool.h](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/Pool.h) +is the Matter SDK pool allocator implementation. + +#### Prefer CopySpanToMutableSpan over memcpy when using spans + +See +[Span.h](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/Span.h) + +#### Prefer std::optional to CHIP implementation in newer code + +The Matter SDK Optional.h was implemented when the Matter SDK was C++14, but +newer code can use std::optional, which offers some benefits over the Matter SDK +implementation (ex. std::optional is trivially destructible if the underlying +type is also trivially destructible) + +### Python + +#### Type hints + +Use type hints on function definitions for public APIs. + +#### Docstrings + +Docstrings should be included for all public APIs. + +#### mypy + +The current python code does not yet pass mypy checks, but we are working +towards this goal. The more compliant new code is to mypy, the better. diff --git a/docs/style/coding/CODING_STYLE_GUIDE-figure1.png b/docs/style/coding/CODING_STYLE_GUIDE-figure1.png deleted file mode 100644 index d8603de93c6067..00000000000000 Binary files a/docs/style/coding/CODING_STYLE_GUIDE-figure1.png and /dev/null differ diff --git a/docs/style/coding/CODING_STYLE_GUIDE.adoc b/docs/style/coding/CODING_STYLE_GUIDE.adoc deleted file mode 100644 index d6436523d657a6..00000000000000 --- a/docs/style/coding/CODING_STYLE_GUIDE.adoc +++ /dev/null @@ -1,721 +0,0 @@ -[.text-center] -= Project Connected Home over IP Software -:listing-caption: *Listing* -:toc: macro -:toclevels: 7 -:sectnumlevels: 7 -:sectanchors: -:sectlinks: - -:plusplus: ++ - -:sectnums!: - -== Best Practices, Coding Conventions, and Style - -[.text-center] -_Revision 5_ + -_2020-09-22_ - -[.text-center] -*Status:* [red]*Approved* / [red]*Active* - -toc::[] - -== Typographic and Syntactic Conventions - -The following syntactic conventions are used throughout this document: - -_shall_:: - -is used to indicate a mandatory rule or guideline that must be adhered -to without exception to claim compliance with this specification. - -_should_:: - -is used to indicate a rule or guideline that serves as a strong -preference to suggested practice and is to be followed in the absence of -a compelling reason to do otherwise. - -_may_:: - -is used to indicate a rule or guideline that serves as a reference to -suggested practice. - -== Introduction - -There are likely as many unique combinations of software engineering and -development standards, conventions, and practices as there organizations -that do such work. This document pulls together those that Project -Connected Home over IP believes best for our organization, its efforts, -and products that consume those efforts, with a particular emphasis on -embedded systems with C or C{plusplus} language development and runtime -environments. - -This document and requirements should be considered canonical for all -Project Connected Home over IP shared infrastructure software, including -both RTOS-based and non-RTOS-based projects on both tightly- and -loosely-constrained system platforms. - -The document is broadly categorized at the highest level into: - -* Best Practices and Conventions -* Format and Style - -And, within conventions, further sub-categorized into those that apply -to: - -* Tightly-constrained -* Loosely-constrained - -system platforms. Applicability to tightly-constrained systems also -generally applies to shared infrastructure software that is used on both -tightly- and loosely-constrained systems. - -link:#id.jzphr1iiku89[Figure 1 below] attempts to illustrate both -qualitative and quantitative applicability of these guidelines to -Project Connected Home over IP software. - -Generally, product-specific applications have the greatest flexibility -and latitude in applying these guidelines to their software. Whereas, -shared infrastructure bears the least flexibility and bears the greatest -adherence to these guidelines. - -image:CODING_STYLE_GUIDE-figure1.png[Figure 1. Graphical summary of the -qualitative and quantitative applicability to Project CHIP software.] - -[[id.jzphr1iiku89]] - -[.text-center] -*Figure 1.* Graphical summary of the qualitative and quantitative -applicability to Project CHIP software. - -:sectnums: - -== Standards - -Project CHIP embedded software development adopts the minimum C and C{plusplus} -standards listed in Table 2.1 below. - -[[t.4d8bfeef046f29261fc72f1a903d6d10a909957a]][[t.2]] - -[cols=3,options="header"] -|=== -|Language |Minimum Standard |Aliases - -|C|ISO9899:1999|ISO C99, C99 -|C{plusplus}|ISO14882:2014|ISO C{plusplus}14, C{plusplus}14 -|=== -[.text-center] -*Table 2.1.* C and C{plusplus} language minimum standards adopted by Project CHIP -software. - -Product-specific software may elect to use later standards to the extent -their software is not broadly shared inside or outside Project CHIP. - -=== C - -Project CHIP embedded software development uses and enforces the -ISO9899:1999 (aka ISO C99, C99) C language standard as the minimum. - -Wherever possible, particularly in non-product-specific, -shared-infrastructure software, toolchain-specific (e.g GCC/GNU) -extensions or the use of later standards shall be avoided or shall be -leveraged through toolchain-compatibility preprocessor macros. - -==== Motivation and Rationale - -At the time of this writing, the C99 standard has been out for over 20 -years. Project CHIP and both the new and contributed source code that -comprise it have only existed for the last seven to eight of those -20-plus years. - -This is beyond more than adequate time for this standard to be pervasive -throughout any toolchain vendor’s C compiler and saves team members from -worrying about ISO9899:1990 (aka ISO C90, C90) portability issues that -have long-since been solved by C99. - -=== C{plusplus} - -Project CHIP embedded software development uses the ISO14882:2014 (aka -ISO C{plusplus}14) language standard as a baseline for source code -compatibility. Conformance with other standards, for example, ISO14882:1998 -(aka ISO C{plusplus}98), may be additionally required in cases where wider -portability is necessary, but in all cases, ISO C{plusplus}14 is the baseline -requirement. - -Wherever possible, particularly in non-product-specific, -shared-infrastructure software, toolchain-specific (e.g GCC/GNU) -extensions or the use of later standards shall be avoided or shall be -leveraged through toolchain-compatibility preprocessor macros. - -==== Motivation and Rationale - -CHIP strives to use the latest C++ functionality as long as existing compilers -support such standards. - -C{plusplus}14 is considered pervasive enough to be used. As compilers start -supporting standards such as C{plusplus}17, C{plusplus}20 and beyond, -CHIP may follow suit. - -== Conventions and Best Practices - -=== Common - -The following sections summarize those best practices that are -independent of particular nuances of either the C or C{plusplus} languages. - -==== When in Rome - -The most important convention and practice in the Project CHIP embedded -software is "_When in Rome..._", per the quote below. - -[quote, St. Ambrose] -____ -If you should be in Rome, live in the Roman manner; if you should be -elsewhere, live as they do there. -____ - -===== Motivation and Rationale - -At this stage in the work group’s and the team’s life cycle, it is rare -the project or subsystem that is entirely new and built from scratch. -More often than not, development will involve extending, enhancing, and -fixing existing code in existing projects. - -When in this situation, it is mandatory you observe how things are done -in this context and do the best that you can to follow the prevailing -conventions present. Not doing so can lead to readability and -maintenance problems down the line and will likely earn you the -disapprobation of the code’s _owner_ or other team members. - -Your extensions or fixes to existing code should be *indistinguishable*, -stylistically, from the original code such that the only way to -ascertain ownership and responsibility is to use the source code control -system’s change attribution (aka _blame_) feature. - -If you find the conventions so foreign or otherwise confusing, it may be -best to let whoever owns the file make the necessary changes or seek the -counsel of others in the group to find out what the right thing to do -is. Never just start changing code wholesale for personal reasons -without consulting others first. - -==== Language-independent - -===== Commenting Out or Disabling Code - -Unused code shall not be disabled by commenting it out with C- or -C{plusplus}-style comments or with preprocessor `#if 0 ... #endif` semantics. - -====== Motivation and Rationale - -Code should either be actively maintained and "in" the source base for a -purpose or removed entirely. Code that is disabled in this way is -generally sloppy and does not convey a sense of certainty and direction -in the code. - -Anyone who is interested in the history of a particular source code file -should use the source code control system to browse it. - -Code that is debug- or test-only should be moved to a conditionally -compiled test source file or conditionalized with an appropriate -`WITH_DEBUG`, `WANT_DEBUG`, `WITH_TESTS`, `WANT_TESTS`, or some similar such -preprocessor mnemonic that can be asserted from the build system. - -===== Use C _stdint.h_ or C{plusplus} _cstdint_ for Plain Old Data Types - -Standard, scalar data types defined in _stdint.h_ \(C) or _cstdint_ (C{plusplus}) -should be used for basic signed and unsigned integer types, especially -when size and serialization to non-volatile storage or across a network -is concerned. - -Examples of these are: `uint8_t`, `int8_t`, etc. - -====== Motivation and Rationale - -These types have been effectively standardized since C99 and should be -available on every platform and provide more neutral portability than -OS-specific types such as `u8`, `UInt8`, etc. Moreover, because these are -pervasive, you do not need to spend any time and energy as a developer -and engineer creating more such types on your own—the compiler vendors -have already done the hard work for you. - -Additionally, using traditional scalar types such as `char`, `int`, `short`, or -`long` have portability issues where data width is concerned because these -types are either signed- or sized-differently on different processor -architectures and and ABIs for those architectures. For example, a char is signed -on some architectures and unsigned on others and a long is 32-bits on some -architectures and 64-bits on others. - -==== Language-dependent - -===== C{plusplus} - -====== Avoid `using namespace` Statements in Headers - -By doing this, you are effectively forcing every other module that -includes the header to also be using the namespace. This causes -namespace pollution and generally defeats the purposes of namespaces. -Fully-qualified symbols should be used instead. - -=== Tightly-constrained Systems and Shared Infrastructure - -Applicability to tightly-constrained systems also generally applies to -shared infrastructure software that is used on both tightly- and -loosely-constrained systems. - -==== Avoid Heap-based Resource Allocation - -Heap-based resource allocation should be avoided. - -===== Motivation and Rationale - -As emphasized throughout this document, the software produced by Project -CHIP is consumed both inside and outside Project CHIP, across a variety -of platforms. The capabilities of these platforms are broad, spanning -soft real-time, deeply-embedded systems based on RTOSes that -may cover life safety and/or physical security applications to richer, -softly-embedded systems based on non-RTOS platforms such as Darwin or -Linux. While the latter are apt to have fully-functional heaps, the -former explicitly may not. - -Consequently, when planning new or extending existing Project CHIP code, -consider the platforms to which the code is targeted. If the platforms -include those deeply-embedded platforms absent functioning heaps, then -heap-based resource allocation is absolutely forbidden. If not, -consideration should be made to the cost / benefit trade-offs of -heap-based allocation and, if possible, it should be avoided using one -of the recommended techniques below. - -===== Alternatives - -In either case, recommended resource allocation alternatives are: - -* In Place Allocation and Initialization -* Pool-based Allocators -* Platform-defined and -assigned Allocators - -The interfaces in https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/CHIPMem.h[_src/lib/support/CHIPMem.h_] provide support for -the latter two alternatives. - -====== Use In Place Allocation and Initialization - -Regardless of whether the source code and runtime are C or C{plusplus}, the -first step is creating storage for the object being allocated and -initialized. For simple -https://en.wikipedia.org/wiki/Passive_data_structure[plain-old-data -(POD)] data structures, this can be done by just allocating the -structure at an appropriate scope. Alternatively, _raw_ storage can be -allocated and then cast. However, great care must be taken with the -latter approach to ensure that natural machine alignments and language -strict-aliasing rules are observed. With the simple data structure -declaration, the compiler does this on your behalf. With the raw -approach, you must do this. - -Once the storage has been allocated, then use symmetric initializers and -deinitializers such as those, for example, for `pthread_attr_t`. An -example is shown in the listing below. - -[source,C,caption='',title='{listing-caption} *{counter:refnum}*. Using in place allocation and initialization in C or C{plusplus}.'] ----- -#include -#include - -... - -// Preprocessor Definitions - -// Allocate the structure using "raw" storage. - -#if defined(__cplusplus) && (__cplusplus >= 201103L) -#include - -#define chipDEFINE_ALIGNED_VAR(name, size, align_type) \ - typename std::aligned_storage::type name; - -#else -#define chipDEFINE_ALIGNED_VAR(name, size, align_type) \ - align_type name[(((size) + (sizeof (align_type) - 1)) / sizeof (align_type))] - -#endif // defined(__cplusplus) && (__cplusplus >= 201103L) - -// Forward Declarations - -extern void * foobar_entry(void *aArgument); - -// Global Variables - -#if USE_STRUCT_STORAGE -// Allocate the structure directly. -static pthread_attr_t sThreadAttributes; - -#elif USE_RAW_STORAGE -static chipDEFINE_ALIGNED_VAR(sThreadAttributes, sizeof (pthread_attr_t), uint64_t); - -#endif // USE_STRUCT_STORAGE - -int foobar() -{ - int retval; - int status; - pthread_t thread; - pthread_attr_t * attrs = (pthread_attr_t *)&sThreadAttributes; - - // Now "construct" or initialize the storage. - retval = pthread_attr_init(attrs); - - if (retval == 0) - { - retval = pthread_create(&thread, attrs, foobar_entry, NULL); - - if (retval == 0) - { - status = pthread_join(thread, NULL); - - if (status != 0) - { - retval = status; - } - - status = pthread_attr_destroy(attrs); - - if (status != 0) - { - retval = status; - } - } - } - - return (retval); -} ----- - -For non-scalar types and objects such as C{plusplus} classes, this gets slightly -trickier since C{plusplus} constructors and destructors must be accounted for -and invoked. Fortunately, C{plusplus} has placement new which handles this. -The listing below modifies the listing above using C{plusplus} placement new -to ensure the class is properly constructed before initialization and -destructed after deinitialization. - -[source,C++,caption='',title='{listing-caption} *{counter:refnum}*. Using C{plusplus} placement new for in place allocation and initialization.'] ----- -#include - -#include -#include - -... - -// Preprocessor Definitions - -// Allocate the structure using "raw" storage. - -#if defined(__cplusplus) && (__cplusplus >= 201103L) -#include - -#define chipDEFINE_ALIGNED_VAR(name, size, align_type) \ - typename std::aligned_storage::type name; - -#else -#define chipDEFINE_ALIGNED_VAR(name, size, align_type) \ - align_type name[(((size) + (sizeof (align_type) - 1)) / sizeof (align_type))] - -#endif // defined(__cplusplus) && (__cplusplus >= 201103L) - -// Type Declarations - -class ThreadAttributes -{ -public: - ThreadAttributes() {}; - ~ThreadAttributes() {}; - - operator pthread_attr_t *() { return &mAttributes; } - -private: - pthread_attr_t mAttributes; -}; - -// Forward Declarations - -extern void * foobar_entry(void *aArgument); - -// Global Variables - -static chipDEFINE_ALIGNED_VAR(sThreadAttributes, sizeof (ThreadAttributes), uint64_t); - -int foobar() -{ - int retval = -1; - int status; - pthread_t thread; - ThreadAttributes * ta; - pthread_attr_t * attrs; - - ta = new (&sThreadAttributes) ThreadAttributes; - - if (ta != NULL) - { - attrs = static_cast(*ta); - - // Now "construct" or initialize the storage. - retval = pthread_attr_init(attrs); - - if (retval == 0) - { - retval = pthread_create(&thread, attrs, foobar_entry, NULL); - - if (retval == 0) - { - status = pthread_join(thread, NULL); - - if (status != 0) - { - retval = status; - } - - status = pthread_attr_destroy(attrs); - - if (status != 0) - { - retval = status; - } - } - } - - ta->~ThreadAttributes(); - } - - return retval; -} ----- - -====== Use Pool-based Allocators - -In place allocation allows the successful allocation, initialization, -deinitialization, and deallocation of a single object allocated from -preallocated storage. However, if the desire exists for a fixed, -configurable pool of objects where 0 to `n` of such objects can be -allocated at any one time, a pool allocator for that specific object -type must be created. - -As shown in the listing below, a pool allocator for a `Foo` class of -`CHIP_FOO_COUNT` objects is effected, assuming the existence of another -helper class, StaticAllocatorBitmap, which uses a bitmap to track the -storage of objects from a static array of storage. - -[source,C++,caption='',title='{listing-caption} *{counter:refnum}*. Using pool-based allocators.'] ----- - -#include - -// Preprocessor Definitions - -// Allocate the structure using "raw" storage. - -#if defined(__cplusplus) && (__cplusplus >= 201103L) -#include - -#define chipDEFINE_ALIGNED_VAR(name, size, align_type) \ - typename std::aligned_storage::type name; - -#else -#define chipDEFINE_ALIGNED_VAR(name, size, align_type) \ - align_type name[(((size) + (sizeof (align_type) - 1)) / sizeof (align_type))] - -#endif // defined(__cplusplus) && (__cplusplus >= 201103L) - -// Type Definitions - -class Foo -{ -public: - Foo(); - Foo(const Foo &inFoo); - ~Foo(); -}; - -// Global Variables - -static chipDEFINE_ALIGNED_VAR(sFooAllocatorBuffer, sizeof (StaticAllocatorBitmap), uint32_t); -static StaticAllocatorBitmap *sFooAllocator; - -static void CreateFooAllocator(void *inStorage, - const StaticAllocatorBitmap::size_type &inStorageSize, - const StaticAllocatorBitmap::size_type &inElementCount, - StaticAllocatorBitmap::InitializeFunction inInitialize, - StaticAllocatorBitmap::DestroyFunction inDestroy) -{ - sFooAllocator = new (sFooAllocatorBuffer) - StaticAllocatorBitmap(inStorage, - inStorageSize, - inElementCount, - inInitialize, - inDestroy); -} - -static StaticAllocatorBitmap &GetFooAllocator() -{ - return *sFooAllocator; -} - -static void *FooInitialize(AllocatorBase &inAllocator, void *inObject) -{ - memset(inObject, 0, sizeof(Foo)); - - return inObject; -} - -static void FooDestroy(AllocatorBase &inAllocator, void *inObject) -{ - return; -} - -int Init() -{ - static const size_t sFooCount = CHIP_FOO_COUNT; - static chipAllocatorStaticBitmapStorageDefine(sFooStorage, Foo, sFooCount, uint32_t, sizeof (void *)); - int retval = 0; - - CreateFooAllocator(sFooStorage, - sizeof (sFooStorage), - sFooCount, - FooInitialize, - FooDestroy); - - return retval; -} - -Foo * FooAllocate() -{ - Foo *foo; - - foo = static_cast(GetFooAllocator().allocate()); - - return foo; -} - -void FooDeallocate(Foo *inFoo) -{ - GetFooAllocator().deallocate(inFoo); -} ----- - -====== Use Platform-defined and -assigned Allocators - -This is a variation on both in place allocation and pool-based -allocation in that it completely delegates resource allocation to the -system integrator and the platform on which the particular software -subsystem is running. - -The advantage of this approach is that it allows the platform to decide -how resource allocation will be handled and allows the package to scale -independently of platform resource allocation. - -The package may define default implementations for a few types of -platform allocation strategies, such as heap-based allocators and -pool-based allocators. - -There are a range of granularities for achieving this type of -delegation, depending on the desired size of the API surface, as shown -in the listings below. - -[source,C++,caption='',title='{listing-caption} *{counter:refnum}*. Using a common allocator method pattern with unique allocators per object, accessed from a unique singleton access per allocator.'] ----- - -chipPlatformInitFooAllocator(); -chipPlatformInitBarAllocator(); -… -foo = chipPlatformGetFooAllocator().allocate(); -… -chipPlatformGetFooAllocator().deallocate(foo); -… -bar = chipPlatformGetBarAllocator().allocate(); -… -chipPlatformGetBarAllocator().deallocate(bar); ----- - -[source,C++,caption='',title='{listing-caption} *{counter:refnum}*. Using a common allocator method pattern with unique allocators per object, accessed from a common singleton access with type per allocator.'] ----- -chipPlatformInitAllocator(CHIP_FOO_T); -chipPlatformInitAllocator(CHIP_BAR_T); -… -foo = chipPlatformGetAllocator(CHIP_FOO_T).allocate(); -… -chipPlatformGetAllocator(CHIP_FOO_T).deallocate(foo); -… -bar = chipPlatformGetAllocator(CHIP_BAR_T).allocate(); -… -chipPlatformGetAllocator(CHIP_BAR_T).deallocate(bar); ----- - -[source,C,caption='',title='{listing-caption} *{counter:refnum}*. Using unique allocators per object.'] ----- -chipPlatformInitFooAllocator(); -chipPlatformInitBarAllocator(); -… -foo = chipPlatformFooAllocate(); -… -chipPlatformFooDeallocate(foo); -… -bar = chipPlatformBarAllocate(); -… -chipPlatformBarDeallocate(bar); ----- - -[source,C,caption='',title='{listing-caption} *{counter:refnum}*. Using a common allocator pattern with unique allocators per object, accessed from a common interface with type per allocator.'] ----- - -chipPlatformInitAllocator(CHIP_FOO_T); -chipPlatformInitAllocator(CHIP_BAR_T); -… -foo = chipPlatformAllocate(CHIP_FOO_T); -… -chipPlatformDeallocate(CHIP_FOO_T, foo); -… -bar = chipPlatformAllocate(CHIP_BAR_T); -… -chipPlatformBarDeallocate(CHIP_BAR_T, bar); ----- - -:sectnums!: - -== Recommended Reading - -While the following references and reading are not part of the formal -best practices, coding conventions, and style cannon, they are -informative and useful guides for improving the style and quality of the -code you write: - -. Jet Propulsion Laboratory. -http://lars-lab.jpl.nasa.gov/JPL_Coding_Standard_C.pdf[JPL -Institutional Coding Standard for the C Programming Language.] Version -1.0. March 3, 2009. -. Jet Propulsion Laboratory. -http://pixelscommander.com/wp-content/uploads/2014/12/P10.pdf[The -Power of Ten – Rules for Developing Safety Critical Code]. December -2014. -. Meyers, Scott. Effective C{plusplus}: 55 Specific Ways to Improve Your -Programs and Designs. Third Edition. 2005. -. Meyers, Scott. More Effective C{plusplus}: 35 New Ways to Improve Your -Programs and Designs. 1996. -. Meyers. Scott. https://www.artima.com/shop/effective_cpp_in_an_embedded_environment[Effective C{plusplus} in an Embedded Environment]. 2015. -. Motor Industry Software Reliability Association. Guidelines for the -Use of the C Language in Critical Systems. March 2013. -. Motor Industry Software Reliability Association. Guidelines for the -Use of the C{plusplus} Language in Critical Systems. June 2008. - -== Revision History - -[cols="^1,^1,<2,<3",options="header"] -|=== -|Revision |Date |Modified By |Description -|5 |2020-09-22 |Grant Erickson |Added Tightly-constrained Systems and Shared Infrastructure > Avoid Heap-based Resource Allocation -|4 |2020-09-15 |Grant Erickson |Added Common > Language-dependent > Avoid `using namespace` Statements in Headers -|3 |2020-09-01 |Grant Erickson |Added Common > Language-independent > Use C _stdint.h_ or C{plusplus} _cstdint_ for Plain Old Data Types -|2 |2020-07-09 |Grant Erickson |Added Common > Language-independent > Commenting Out or Disabling Code -|1 |2020-07-08 |Grant Erickson |Initial revision. -|=== - -[.text-center] -_Project Connect Home over IP Public Information_