https://RustRocket.rs -- Cloud Monk Losang Jinpa, Ph.D., MCSE / MCT, https://Rustaceans.rs, Full Stack Cloud Native Rust DevOps Engineer - Rocket Framework Rust Microservices on Kubernetes-AWS-Azure-GCP

Return to Fluent C Table of Contents, Fluent C, C Language Design Patterns, C Language, C Language Bibliography, C Language Courses, C Language DevOps - C Language CI/CD, C Language Security - C Language DevSecOps, C Language Functional Programming, C Language Concurrency, C Language Data Science - C Language and Databases, C Language Machine Learning, C Language Glossary, Awesome C Language, C Language GitHub, C Language Topics

“ (FlueC 2023)

Fair Use Source: 1492097330 (FlueC 2023)

Overview of the Patterns:

You’ll find an overview of all patterns presented in this book in Table P-2, Table P-3, Table P-4, Table P-5, Table P-6, Table P-7, Table P-8, Table P-9, and Table P-10. The tables show a short form of the patterns that only contains a brief description of the core problem, followed by the keyword “Therefore”, followed by the core solution.

Table P-2. Patterns on Error Handling

Pattern Name and Summary

“Function Split”:

The function has several responsibilities and that makes the function hard to read and hard to maintain. Therefore, split it up. Take a part of a function that seems useful on its own, create a new function with that, and call that function.

“Guard Clause”:

The function is hard to read and hard to maintain because it mixes pre-condition checks with the main functionality of the function. Therefore, check whether you have mandatory pre-conditions and immediately return from the function if these pre-conditions are not met.

“Samurai Principle”

When returning error information, you assume that the caller checks for this information. However, the caller can simply omit this check and the error might go unnoticed. Therefore, return from a function victorious or not at all. If there is a situation for which you know that an error cannot be handled, then abort the program.

“Goto Error Handling”

Code gets difficult to read and to maintain if it acquires and cleans up multiple resources at different places within a function. Therefore, have all resource cleanup and error handling at the end of the function. If a resource cannot be acquired, use the goto statement to jump to the resource cleanup code.

“Cleanup Record”

It is difficult to make a piece of code easy to read and to maintain if this code acquires and cleans up multiple resources, in particular if those resources depend on one another. Therefore, call resource acquisition functions as long as they succeed and store which functions require cleanup. Call the cleanup functions depending on these stored values.

“Object-Based Error Handling”

Having multiple responsibilities in one function, such as resource acquisition, resource cleanup and usage of that resource, make that code difficult to implement, difficult to read, difficult to maintain and difficult to test. Therefore, put initialization and cleanup into separate functions similar to the concept of constructors and destructors in object-oriented programming.

Table P-3. Patterns on Returning Error Information

Pattern Name and Summary

“Return Error Codes”

You want to have a mechanism to transport error information to the caller, so that the caller can react to it. You want the mechanism to be simple to use, and the caller should be able to clearly distinguish between different error situations that could occur. Therefore, use the Return Value of a function to transport error information. Return a value that represents a specific kind of error. You as the callee and the caller must have a mutual understanding of what the value means.

“Return Relevant Errors”

On the one hand, the caller should be able to react to errors; on the other hand the more error information you return, the more your code and the code of your caller has to deal with error handling, which makes the code longer. Longer code is harder to read and maintain and brings in the risk of additional bugs. Therefore, only transport error information to the caller if that information is relevant to the caller. Error information is only relevant to the caller if the caller can react to that information.

“Special Return Values”

You want to transport error information, but it’s not an option to explicitly Return Error Codes, because that implies that you cannot use the Return Value of the function to return other data, and you’d have to transport that data via Out-Parameters, which would make calling your function more difficult. Therefore, use the Return Value of your function to transport the data computed by the function. Reserve one or more special values to be returned if an error occurs.

“Log Errors”

You want to make sure that in case of an error you can easily find out its cause. However, you don’t want your error handling code to become complicated because of that. Therefore, use different channels to transport error information that is relevant for the calling code and error information that is relevant for the developer. For example, write debug error information into a log file and don’t return the detailed debug error information to the caller.

Table P-4. Patterns on Memory Management Pattern Name and Summary

“Stack First”

Deciding the storage-class and memory section (stack, heap, …) for variables is a decision every programmer has to make often. It gets exhausting if for each and every variable, the pros and cons of all possible alternatives have to be considered in detail. Therefore, simply put your variables by default on the stack to profit from automatic cleanup of stack variables.

“Eternal Memory”

Holding large amounts of data and transporting it between function calls is difficult, because you have to make sure that the memory for the data is large enough and that the lifetime extends across your function calls. Therefore, put your data into memory that is available throughout the whole lifetime of your program.

“Screw Freeing”

Having dynamic memory is required if you need large amounts of memory and memory where you don’t know the required size beforehand. However, handling cleanup of dynamic memory is a hassle and is the source of many programming errors. Therefore, allocate dynamic memory and let the operating system cope with deallocation by the end of your program.

“Dedicated Ownership”

The great power of using dynamic memory comes with the great responsibility of having to properly clean that memory up. In larger programs, it becomes difficult to make sure that all dynamic memory is cleaned up properly. Therefore, right at the time when you implement memory allocation, clearly define and document where it’s going to be cleaned up and who is going to do that.

“Allocation Wrapper”

Each allocation of dynamic memory might fail, so you should check allocations in your code to react accordingly. That is cumbersome because you have many places for such checks in your code. Therefore, wrap the allocation and deallocation calls and implement error handling or additional memory management organization in these wrapper functions.

“Pointer Check”

Programming errors that lead to accessing an invalid pointer cause uncontrolled program behavior, and such errors are difficult to debug. However, because your code works a lot with pointers, there is a good chance that you introduced such programming errors. Therefore, explicitly invalidate uninitialized or freed pointers and always check pointers for validity before accessing them.

“Memory Pool”

Frequently allocating and deallocating objects from the heap leads to memory fragmentation. Therefore, hold a large piece of memory throughout the whole lifetime of your program. At runtime, retrieve fixed-size chunks of that memory pool instead of directly allocating new memory from the heap.

Table P-5. Patterns on Returning Data from C Functions Pattern Name and Summary

“Return Value”

The function parts you want to split are not independent from one another. As usual in procedural programming, some part delivers a result that is then needed by some other part. The function parts that you want to split need to share some data. Therefore, simply use the one C mechanism intended to retrieve information about the result of a function call: the Return Value. The mechanism to return data in C copies the function result and provides the caller access to this copy.

“Out-Parameters”

C only supports returning a single type from a function call and that makes it complicated to return multiple pieces of information. Therefore, return all the data with one single function call by emulating by-reference arguments with pointers.

“Aggregate Instance”

C only supports returning a single type from a function call and that makes it complicated to return multiple pieces of information. Therefore, put all data that is related together into a newly defined type. Define this Aggregate Instance to contain all the related data that you want to share. Define it in the interface of your component to let the caller directly access all the data stored in the instance.

“Immutable Instance”

You want to provide information held in large pieces of immutable data from your component to a caller. Therefore, have an instance (for example, a struct) containing the data to share in static memory. Provide this data to users who want to access it and make sure that they cannot modify it.

“Caller-Owned Buffer”

You want to provide complex or large data of known size to the caller and that data is not immutable - it changes at runtime. Therefore, require the caller to provide a buffer and its size to the function that returns the complex, large data. In the function implementation, copy the required data into the buffer if the buffer size is large enough.

“Callee Allocates”

You want to provide complex or large data of unknown size to the caller, and that data is not immutable (it changes at runtime). Therefore, allocate a buffer with the required size inside the function that provides the complex, large data. Copy the required data into the buffer and return a pointer to that buffer.

Table P-6. Patterns on Data Lifetime and Ownership Pattern Name and Summary

“Stateless Software-Module”

You want to provide logically related functionality to your caller and you and make that functionality for the caller as easy as possible to use. Therefore, keep your functions simple and don’t build up state information in your implementation. Put all related functions into one header file and provide the caller this interface to your software-module.

“Software-Module with Global State”

You want to structure your logically related code that requires common state information and you want to make that functionality for the caller as easy as possible to use. Therefore, have one global instance to let your related functions share common resources. Put all functions that operate on that instance into one header file and provide the caller this interface to your software-module.

“Caller-Owned Instance”

You want to provide multiple callers access to functionality with functions that depend on one another and the interaction of the caller with your functions builds up state information. Therefore, require the caller to pass an instance, which is used to store resource and state information, along to your functions. Provide explicit functions to create and destroy these instances, so that the caller can determine their lifetime.

“Shared Instance”

You want to provide multiple callers access to functionality with functions that depend on one another and the interaction of the caller with your functions builds up state information, which your callers want to share. Therefore, require the caller to pass an instance, which is used to store resource and state information, along to your functions. Use the same instance for multiple callers and keep the ownership of that instance in your software-module.

Table P-7. Patterns on Flexible APIs Pattern Name and Summary

“Header Files”

You want some functionality that you implement to be accessible for code from other implementation files, but you want to hide your implementation details from the caller. Therefore, provide function declarations in your API for any functionality you want to provide to your user. Hide any internal functions, internal data, and your function definitions (the implementations) in your implementation file and don’t provide this implementation file to the user.

“Handle”

You have to share state information or operate on shared resources in your function implementations, but you don’t want your caller to see or even access all that state information and shared resources. Therefore, have a function to create the context on which the caller operates and return an abstract pointer to internal data for that context. Require the caller to pass that pointer to all your functions which can then use the internal data to store state information and resources.

“Dynamic Interface”

It should be possible to call implementations with slightly deviating behaviors, but it should not be necessary to duplicate any code, not even the control logic implementation and interface declaration. Therefore, define a common interface for the deviating functionalities in your API and require the caller to provide a callback function for that functionality which you then call in your function implementation.

“Function Control”

You want to call implementations with slightly deviating behaviors, but you don’t want to duplicate any code, not even the control logic implementation or the interface declaration. Therefore, apply data-based abstraction. Add a parameter to your function that passes meta-information about the function call and that specifies the actual functionality to be performed.

Table P-8. Patterns on Iterator Interfaces

Pattern Name and Summary

“Index Access”

You want to make it possible for the user to iterate elements in your data structure in a convenient way, and it should be possible to change internals of the data structure without resulting in changes to the user’s code. Therefore, provide a function that takes an index to address the element in your underlying data structure and return the content of this element. The user calls this function in a loop to iterate over all elements.

“Cursor Iterator”

You want to provide an iteration interface to your user which is robust in case the elements change during the iteration and which enables you to change the underlying data structure at a later point in time without requiring any changes to the user’s code. Therefore, create an iterator instance that points to an element in the underlying data structure. An iteration function takes this iterator instance as argument, retrieves the element the iterator currently points to, and modifies the iteration instance to point to the next element. The user then iteratively calls this function to retrieve one element at a time.

“Callback Iterator”

You want to provide a robust iteration interface which does not even require the user to implement a loop in the code for iterating over all elements and and which enables you to change the underlying data structure at a later point in time without requiring any changes to the user’s code. Therefore, use your existing data structure specific operations to iterate over all your elements within your implementation and call some provided user-function on each element during this iteration. This user-function gets the element content as a parameter and can then perform its operations on this element. The user just calls one function to trigger the iteration and the whole iteration takes place inside your implementation.

Table P-9. Patterns on Organizing Files in Modular Programs

Pattern Name and Summary

“Include Guard”

It’s easy to include a header file multiple times, but including one and the same header file leads to compile errors if types or certain macros are part of it, because during compilation they get redefined. Therefore, protect the content of your header files against multiple inclusion so that the developer using the header files does not have to care whether it is included multiple times. Use an interlocked #ifdef statement or a #pragma once statement to achieve that.

“Software-Module Directories”

Splitting code into different files increases the number of files in your codebase. Having all files in one single directory makes it difficult to keep an overview of all the files, in particular for large codebases. Therefore, put header files and implementation files that belong to a tightly coupled functionality into one directory. Name that directory after the functionality that is provided via the header files.

“Global Include Directory”

To include files from other software modules, you have to use relative paths like ../othersoftwaremodule/file.h. You have to know the exact location of the other header file. Therefore, have one global directory in your codebase that contains all software-module APIs. Add this directory to the global include paths in your toolchain.

“Self-Contained Component”

From the directory structure it is not possible to see the dependencies in the code. Any software-module can simply include the header files from any other software-module, so it’s impossible to check dependencies in the code via the compiler. Therefore, identify software-modules that contain similar functionality and that should be deployed together. Put these software-modules into a common directory and have a designated subdirectory for their header files that are relevant for the caller.

“API Copy”

You want to develop, version, and deploy the parts of your codebase independently from one another. However, to do that, you need clearly defined interfaces between the code parts and to be able to separate that code into different repositories. Therefore, to use the functionality of another component, copy its API. Build that other component separately and copy the build artifacts and its public header files. Put these files into a directory inside your component and configure that directory as a global include path.

Table P-10. Patterns to Escape #ifdef Hell

Pattern Name and Summary

“Avoid Variants”

Using different functions for each platform makes the code harder to read and harder to write. The programmer is required to initially understand, to correctly use, and to test these multiple functions in order to achieve one single functionality across multiple platforms. Therefore, use standardized functions, which are available on all platforms. If there are no standardized functions, consider not implementing the functionality.

“Isolate Primitives”

Having code variants organized with #ifdef statements makes the code unreadable. It is very difficult to follow the program flow, because it is implemented multiple times for multiple platforms. Therefore, isolate your code variants. In your implementation file, put the code handling the variants into separate functions and call these functions from your main program logic, which then only contains platform independent code.

“Atomic Primitives”

The function that contains the variants and is called by the main program is still hard to comprehend, because all the complex

1. ifdef code was simply put into this function in order to get rid of it in the main program. Therefore, make your primitives atomic. Only handle exactly one kind of variant per function. If you handle multiple kinds of variants, for example, operating system variants and hardware variants, then have separate functions for that.

“Abstraction Layer”

You want to use the functionality which handles platform variants at several places in your codebase, but you do not want to duplicate the code of that functionality. Therefore, provide an API for each functionality that requires platform specific code. Define only platform independent functions in the header file and put all platform specific

1. ifdef code into the implementation file. The caller of your functions only includes your header file and does not have to include any platform specific files.

“Split Implementation Variants”

The platform specific implementations still contain #ifdef statements to distinguish between code variants. That makes it difficult to see and to select which part of the code should be built for which platform. Therefore, put each variant implementation into a separate implementation file and select per file what you want to compile for which platform.

Fair Use Sources:

• Fluent C by Christopher Preschern on DuckDuckGo
• 1492097330 (FlueC 2023)