c_error_handling.tex

% Copyright (c) 2018-2019 Matjaž Guštin <dev@matjaz.it>
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are met:
% 
% 1. Redistributions of source code must retain the above copyright notice,
%    this list of conditions and the following disclaimer.
% 2. Redistributions in binary form must reproduce the above copyright
%    notice, this list of conditions and the following disclaimer in the
%    documentation and/or other materials provided with the distribution.
% 3. Neither the name of the copyright holder nor the names of its
%    contributors may be used to endorse or promote products derived from
%    this software without specific prior written permission.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
% POSSIBILITY OF SUCH DAMAGE.

\documentclass[aspectratio=169,14pt]{beamer}
\newcommand{\bminipath}{bmini}
\newcommand{\presentationauthor}{Matjaž GUŠTIN}
\newcommand{\presentationtitle}{Error handling design patterns in non-OOP languages}
\newcommand{\presentationsubtitle}{Namely in ISO C}
\newcommand{\presentationabstract}{Design Patterns KU assignment}
\input{\bminipath/bmini.tex}

\date{2019-01-09}

\begin{document}

\begin{frame}
\titlepage
\end{frame}



\begin{frame}[label=material]{Material}
\begin{itemize}
    \item Slides available on \href{https://matjaz.it/slides/}{\textbf{matjaz.it/slides}} 
    \item Slides licensed under a 
    \href{https://creativecommons.org/licenses/by/4.0/}{Creative~Commons~Attribution~4.0~International~License~(CC~BY~4.0)}
    \item LaTeX source code available at
    \href{https://github.com/TheMatjaz/c_error_handling_design_patterns}{github.com/TheMatjaz/c\_error\_handling\_design\_patterns}
\end{itemize}
\end{frame}



\begin{frame}{Overview}
\begin{enumerate}
    \item A brief recap over Exceptions
    \item Return codes\\
    \begin{enumerate}
        \item Boolean codes
        \item Error codes
        \item Error flags
    \end{enumerate}
    \item Using the return value's domain
    \item Embedded error indicator in data type
    \item \texttt{<errno.h>}
    \item \texttt{<setjmp.h>}
    \item Code design choices with return codes
\end{enumerate}

\textbf{Note}: it will be very code-based and development-focused
\end{frame}





\section{A brief recap over Exceptions}

\begin{frame}{Exceptions}
In OOP languages we commonly have the \textbf{Exception} classes used to handle:
\begin{itemize}
    \item unexpected values or states
    \item special cases
    \item non-nominal situations
    \item ... something that cannot be handled the normal way
\end{itemize}
\end{frame}



\begin{frame}{Problem and forces}
\begin{itemize}
    \item Need a way to indicate to the function caller that something could not be done and why.
    \item Exceptions are not available.
    \item Must be simple, lightweight, efficient, easy to understand.
\end{itemize}
\end{frame}





\section{Return codes}

\begin{frame}{Return codes}
\begin{itemize}
    \item Also known as \textit{status codes}
    \item The function's return value indicates its execution success or failure
    \item Different levels of detail
    \item A potential way to categorize them\footnote{This is just my proposal, as often all these terms are used interchangeably}\\
    \begin{enumerate}
        \item Boolean codes
        \item Error codes
        \item Error flags
    \end{enumerate}
\end{itemize}
\end{frame}



\begin{frame}[fragile]{Boolean return code}
\begin{lstlisting}[style=cstyle]
#include <stdbool.h>

bool receive_message(message_t* message);

// Alternate version without booleans
int receive_message(message_t* message);
\end{lstlisting}

\begin{description}
    \item[\texttt{true}] (or non-0) on success
    \item[\texttt{false}] (or 0) on failure
\end{description}
\end{frame}



\begin{frame}[fragile]{Boolean return code: consequences}
\begin{itemize}
    \item[\bad] Confusing: does \texttt{false} indicate \quotes{no error} or \quotes{no success}?
    \item[\bad] Why did it fail?
    \item[\bad] Can we retry or not? Maybe with different settings?
\end{itemize}
\end{frame}



\begin{frame}[fragile]{Error code}
\begin{lstlisting}[style=cstyle]
typedef enum {
    RX_OK = 0,
    ERROR_TIMEOUT_NOTHING_RECEIVED,
    ERROR_BROKEN_CRC,
    ERROR_INCOMPLETE_MESSAGE,
    ERROR_ANTENNA_DISCONNECTED,
} rx_code_t;

rx_code_t receive_message(message_t* message);
\end{lstlisting}

\begin{description}
    \item[\texttt{RX\_OK}] on success. OK is \texttt{false} to indicate the \textit{absence} of errors.
    \item[Others] on failure. The actual value indicates the exact reason.
\end{description}
\end{frame}



\begin{frame}[fragile]{Error code: consequences}
\begin{itemize}
    \item[\good] Cleaner setup
    \item[\good] We can handle different failure cases in different ways
    \item[\good] Easy to remember which value is the success: the \texttt{false} value
    \item[\good] \textbf{Arguably the most common pattern} outside of \texttt{libc}
    \item[\bad] Longer code handling the cases
\end{itemize}
\end{frame}



\begin{frame}[fragile]{Usage examples: error code}
\begin{lstlisting}[style=cstyle]
message_t rx_message;
rx_code_t error;

error = receive_message(&rx_message);
if (error != RX_OK) {  // Simply: if (error) {...}
    puts("Reception failure");
}
\end{lstlisting}
\end{frame}



\begin{frame}[fragile]{}
\begin{lstlisting}[style=cstyle,basicstyle=\scriptsize\ttfamily]
message_t rx_message;
rx_code_t rx_code;
bool keep_receiving = true;

do {
    rx_code = receive_message(&rx_message);
    switch (rx_code) {
        case (RX_OK): {
            process_message(&rx_message);
            break;
        }
        case (ERROR_TIMEOUT_NOTHING_RECEIVED) {
            sleep(5);
            break;
        }
        case (ERROR_ANTENNA_DISCONNECTED) {
            puts("Please connect the antenna to the PC");
            keep_receiving = false;
            break;
        }
        default: {} // Do nothing, just retry the reception.
    }
} while (keep_receiving);
\end{lstlisting}
\end{frame}



\begin{frame}{Usage examples: process exit status}
\begin{itemize}
    \item Also known as \textit{exit code} or \textit{error level}.
    \item Value that a process returns after its termination to the parent process.
    \item Usually \texttt{int32} where 0 means OK: process completed successfully.
    \item Non-zero values are not standardized: every OS has a different list of recommended/preferred interpretations.
    \item In C: the \texttt{int} value returned by \texttt{main()}. Alternatively the argument of \texttt{exit()}.
\end{itemize}
\end{frame}



\begin{frame}[fragile]{Error flags}
\begin{lstlisting}[style=cstyle]
typedef enum {
    // Bit flags, each value on different bit
    RX_OK = 0x00,
    ERROR_TIMEOUT_NOTHING_RECEIVED = 0x01,
    ERROR_BROKEN_CRC = 0x02,
    ERROR_INCOMPLETE_MESSAGE = 0x04,
    ERROR_ANTENNA_DISCONNECTED = 0x08,
} rx_flag_t;
typedef uint8_t rx_code_t;

rx_code_t receive_message(message_t* message);
\end{lstlisting}

\begin{description}
    \item[\texttt{RX\_OK}] on success. No flags or \texttt{false} to indicate the \textit{absence} of errors.
    \item[Any flag] on failure. Each bit expresses one reason. More than one reason possible \textbf{simultaneously}.
\end{description}
\end{frame}



\begin{frame}[fragile]{Error flags: consequences}
\textbf{In addition} to the consequences of Error codes:

\begin{itemize}
    \item[\good] Useful if multiple failures can happen simultaneously
    \item[\bad] \(N\) bits indicate only \(N\) errors. Error codes indicate \(2^N - 1\). Bigger integer types may be needed.
    \item[\bad] Even longer code handling the cases: need to handle all possible flags independently (e.g. a series of \texttt{if-if-if} but not \texttt{switch-case})
    \item[\bad] Sometimes macros are involved for operations on groups of flags
\end{itemize}
\end{frame}





\section{Using the return value's domain}

\begin{frame}[fragile]{Return values outside the domain}

\begin{itemize}
    \item The function returns a value, not a return code.
    \item The value has a limited domain.
    \item When value out of bounds, indicates an error.
\end{itemize}

Example: writing formatted strings to a file.

\begin{lstlisting}[style=cstyle]
int fprintf ( FILE * stream, const char * format, ... );
\end{lstlisting}

Returns the amount of characters written: 0 or more.\\
\textbf{Negative on failure}. 
\end{frame}



\begin{frame}[fragile]{Outside the domain: consequences}
\begin{itemize}
    \item[\good] No need for additional enums
    \item[\good] Easy to understand if something is wrong (e.g. negative length does not make sense)
    \item[\bad] Easy to forget to check and use error value as a good result
    \item[\bad] Must read documentation of function in detail 
    \item[\bad] Not possible if no value outside the domain exists
\end{itemize}
\end{frame}





\section{Embedded error indicator in data type}

\begin{frame}{Nullable types}
The language's type system supports every value to be either \texttt{NULL}-like indicating missing data or a value.

\begin{itemize}
    \item In Python anything can be \texttt{None}
    \item In SQL anything can be \texttt{NULL}
    \item In Java non-primitives only (\texttt{int} no, \texttt{Integer} yes): \textit{Null object pattern}
    \item In C works only with pointers
\end{itemize}
\end{frame}



\begin{frame}[fragile]{A simple pointer}
A pointer to something may be \texttt{NULL} (have the value 0) to indicate the broken link. Otherwise it can be dereferenced.

\begin{lstlisting}[style=cstyle]
#include <stdio.h>
#include <stdint.h>

int main() {
    uint8_t* buffer = malloc(50);
    if (buffer != NULL) {
        puts("Malloc succeeded and I have a buffer");
    } else {
        puts("Malloc failed");
    }
    return 0;
}
\end{lstlisting}
\end{frame}



\begin{frame}[fragile]{A simple pointer: consequences}
\begin{itemize}
    \item[\good] Embedded in most programming languages
    \item[\good] Every programmer understands: cannot work on \texttt{NULL}
    \item[\good] No need for checking a separate error code
    \item[\bad] Very easy to forget to check and dereference \texttt{NULL} (auch!)
    \item[\bad] Dereferencing may be too slow
    \item[\meh] In embedded environments may be possible work due to missing \texttt{malloc()}
    \item[\meh] May make the code less readable (\texttt{int*} vs \texttt{int})
\end{itemize}
\end{frame}



\begin{frame}[fragile]{Option(al) types}
Polymorphic type representing a value that may or may not have meaning. Mostly functional languages.
\begin{itemize}
    \item In Rust: \texttt{enum Option<T> \{ None, Some(T) \}}
    \item In Haskell: \texttt{data Maybe a = Nothing | Just a}
    \item In C\#: \texttt{Nullable<T>} or \texttt{T?}
    \item In C: manually...
\begin{lstlisting}[style=cstyle]
struct optional_uint32 {
    uint8_t error_code;  // Indicate if the value makes sense
    uint32_t value;      // Actual value
};
\end{lstlisting}
\end{itemize}
\end{frame}



\begin{frame}{IEEE 754 floating-point values}
The IEEE encoding of the real numbers has embedded handling of special cases.

\begin{itemize}
    \item \( + \infty \)\\
    \begin{itemize}
        \item division by (positive) zero: \texttt{1.0/0.0}
        \item overflows: \texttt{pow(10.0, 500.0)}
        \item always bigger than any other value
        \item to check: \texttt{isinf(value) \&\& value > 0}
    \end{itemize}

    \item \( - \infty \)\\
    \begin{itemize}
        \item division of negative value by zero: \texttt{-1.0/0.0}
        \item or by negative zero: \texttt{1.0/-0.0}
        \item underflows: \texttt{pow(-10.0, 501.0)}
        \item always smaller than any other value
        \item to check: \texttt{isinf(value) \&\& value < 0}
    \end{itemize}
\end{itemize}
\end{frame}



\begin{frame}{IEEE 754 floating-point values (cont.)}
\begin{itemize}
    \item \texttt{NaN} (Not a Number)\\
    \begin{itemize}
        \item invalid operations
        \begin{itemize}
            \item \texttt{0.0/0.0}
            \item \texttt{Infinity * 0.0}
            \item \texttt{sqrt(-1.0)}
        \end{itemize}
        \item propagating: operations on a \texttt{NaN} return \texttt{NaN}
        \item comparing with a \texttt{NaN} always returns \texttt{false}
        \item has a quiet (just returning) and signaling variant (FPU/floatlib indicates error to the system)
        \item it even has free bits to encode type of error (rare)
        \item to check: \texttt{isnan(value)}
    \end{itemize}
    \item combined check: \texttt{isfinite(value)} returns \texttt{true} when the value is not \texttt{NaN} or \( \pm \infty \)
\end{itemize}
\end{frame}



\begin{frame}{IEEE 754 floating-point values: consequences}
\begin{itemize}
    \item[\good] IEEE standard since decades, really every computer supports it
    \item[\good] Hardware accelerated
    \item[\good] No need for pointer dereferencing or checking a separate error code
    \item[\bad] Easy to forget to check with \texttt{isfinite()}
\end{itemize}
\end{frame}





\section{\texttt{<errno.h>}}

\begin{frame}[fragile]{\texttt{<errno.h>}}
A standard, glorified global error code.

\begin{lstlisting}[style=cstyle]
#include <stdio.h>
#include <errno.h>   // To access the integer `errno`
#include <string.h>  // To convert `errno` to a human-readable string with strerror()

int main() {
    printf("At startup: value=%d, string=%s\n",
    errno, strerror(errno));
    FILE *file = fopen("NON_existing_file.txt", "r");
    if (file == NULL) {
        printf("After fopen fails: value=%d, string=%s\n",
        errno, strerror(errno));
    } else { fclose(file); }
    return 0;
}
\end{lstlisting}
\end{frame}



\begin{frame}{\texttt{<errno.h>}: consequences}
\begin{itemize}
    \item[\good] Part of C standard library
    \item[\bad] Easy to lose track who set the \texttt{errno} variable in nested code
    \item[\bad] Global variables are bad
\end{itemize}
\end{frame}





\section{\texttt{<setjmp.h>}}

\begin{frame}[fragile]{\texttt{<setjmp.h>}}
\begin{lstlisting}[style=cstyle]
int setjmp (jmp_buf env);
\end{lstlisting}
\begin{itemize}
    \item Fills \texttt{env} with the current state of the calling environment, so it can be restored later.
    \item Returns 0 on direct invocation (when state is saved).
    \item Otherwise returns the value (forcibly non-zero) passed by \texttt{longjmp()} (when state is restored).
\end{itemize}
\end{frame}



\begin{frame}[fragile]{\texttt{<setjmp.h>} (cont.)}
\begin{lstlisting}[style=cstyle]
void longjmp (jmp_buf env, int val);
\end{lstlisting}
\begin{itemize}
    \item Restores stored \texttt{env}.
    \item Transfers the control to the point where \texttt{setjmp()} was last used to fill the \texttt{env}.
    \item Makes \texttt{setjmp()} return \texttt{val}.
    \item This function never returns (jumping to \texttt{setjmp()} before that).
\end{itemize}
\end{frame}



\begin{frame}[fragile]{}
\begin{lstlisting}[style=cstyle]
#include <stdio.h>
#include <setjmp.h>

static jmp_buf state;
typedef enum {
    OK = 0,
    NEGATIVE_VALUE = 1,
    TOO_BIG_VALUE = 2,
} error_code_t;

int twice4(int value) {
    if (value < 0) {
        printf("(!) Negative value: %d\n", value);
        longjmp(state, NEGATIVE_VALUE); // Restore state, set code
    } else if (value > 100) {
        printf("(!) Too big value: %d\n", value);
        longjmp(state, TOO_BIG_VALUE);  // Restore state, set code
    } else { return 2 * value; }
}
\end{lstlisting}
\end{frame}



\begin{frame}[fragile]{}
\begin{lstlisting}[style=cstyle]
int twice3(int value) { return twice4(value); }
int twice2(int value) { return twice3(value); }
int twice(int value)  { return twice2(value); }

int main() {
    // Initially saves state and sets error_code to 0.
    // Jumped to using longjmp(state, new_value),
    // setting error_code to new_value.
    int error_code = setjmp(state);
    if (error_code == OK) {
        int input = -10;  // -10 or 1000 jumps to else branch
        int result = twice(input);
        printf("Twice of %d is %d\n", input, result);
    } else {
        printf("Error code %d\n", error_code);
    }
    return 0;
}
\end{lstlisting}
\end{frame}



\begin{frame}{\texttt{<setjmp.h>}: consequences}
\begin{itemize}
    \item[\good] Breaking control flow
    \item[\good] Good performance (avoiding functions return calls)
    \item[\good] A way to implement exception-like behaviour
    \item[\bad] Like \texttt{goto} but worse: may be \textbf{very} confusing
    \item[\bad] Often readability is more important than premature optimization
\end{itemize}
\end{frame}






\section{Code design choices with return codes}

\begin{frame}[fragile]{Nested return codes problem}
\begin{lstlisting}[style=cstyle]
tx_code_t transmit_message(message_t* message) {
    tx_code_t tx_error = TX_OK;
    encoding_code_t encoding_error = ENC_OK;
    
    encoding_error = prepare_message(message);
    if (encoding_error) {
        return ???;  // Which error code should we return?
    }
    ...
}
\end{lstlisting}
\end{frame}



\begin{frame}{Nested return codes problem (cont.)}
\begin{itemize}
    \item Returning the inner error code \texttt{encoding\_error} breaks abstraction layers
    \item Returning the outer error code \texttt{tx\_error} may hide details
\end{itemize}
\end{frame}



\begin{frame}[fragile]{Nested return codes: solution 1}
One huge \texttt{enum} containing every possible error\\
(Example: SQLite < v3.3.8)

\begin{lstlisting}[style=cstyle]
typedef enum {
    TX_OK = 0,
    ERROR_ENCODING_HEADER,
    ERROR_ENCODING_BODY,
    ERROR_WRONG_CONFIGURATION,
    ERROR_ANTENNA_DISCONNECTED,
} tx_code_t;

tx_code_t transmit_message(message_t* message) {
    tx_code_t tx_error = RX_OK;
    
    tx_error = prepare_message(message);
    if (tx_error) { return tx_error; }
    ...
\end{lstlisting}
\end{frame}



\begin{frame}{Solution 1: consequences}
\begin{itemize}
    \item[\good] Every library function (inner and outer) returns the same data type
    \item[\good] Easy to write library: on error, just pass error code to caller
    \item[\good] Easy to write application: only one \texttt{enum} to handle
    \item[\bad] Abstraction layers are broken
    \item[\bad] Hard to understand which function from an API may return which codes
\end{itemize}
\end{frame}




\begin{frame}[fragile]{Nested return codes: solution 2}
Combined error codes\\
(Example: ISO/IEC 7816 for smart cards)

\begin{minipage}[t]{0.3\textwidth}
\begin{lstlisting}[style=cstyle]
typedef enum {
    TX_OK = 0,
    ERR_ENCODING,
    ERR_ANTENNA,
} tx_categ_t;
\end{lstlisting}
\end{minipage}
\begin{minipage}[t]{0.3\textwidth}
\begin{lstlisting}[style=cstyle]
typedef enum {
    ENC_OK = 0,
    ENC_HEADER,
    ENC_BODY,
} tx_encoding_t;
\end{lstlisting}
\end{minipage}
\begin{minipage}[t]{0.3\textwidth}
\begin{lstlisting}[style=cstyle]
typedef enum {
    ANT_OK = 0,
    ANT_DISCONN,
} tx_antenna_t;
\end{lstlisting}
\end{minipage}

\begin{lstlisting}[style=cstyle]
uint16_t transmit_message(message_t* message) {
    uint8_t tx_error_low = 0;
    tx_error_low = prepare_message(message);
    if (tx_error_low) { return (ERR_ENCODING<<8) | tx_error_low; }
    ...
\end{lstlisting}
\end{frame}



\begin{frame}{Solution 2: consequences}
\begin{itemize}
    \item[\good] Abstraction layers are "less" broken: every byte is on its own layer
    \item[\good] Easy to understand which function from an API may return which codes
    \item[\bad] Error codes need to be combined before returning
    \item[\bad] Error codes need to be unpacked before inspection
    \item[\meh] The application may ignore the "more detailed byte"
\end{itemize}
\end{frame}





\section{Conclusion}

\begin{frame}{Wrapping up}
\begin{itemize}
    \item If your programming language supports exceptions or nullable/option types: use them
    \item Otherwise go with return error codes or flags: 0 for OK, other values for error cases
    \item Write the error handling code with care, focus on \textbf{readability}
\end{itemize}
\end{frame}



\begin{frame}{Sources}
\begin{small}
    \begin{itemize}
        \item \url{http://www.cplusplus.com/reference/}
        \item \url{https://en.wikipedia.org/wiki/Exception_handling}
        \item \url{https://en.wikipedia.org/wiki/Exit_status}
        \item \url{https://en.wikipedia.org/wiki/Nullable_type}
        \item \url{https://en.wikipedia.org/wiki/Floating-point_arithmetic\#Special_values}
        \item Robert C. Martin, \textit{Clean Code: A Handbook of Agile Software Craftsmanship}, ISBN-10: 9780132350884 
    \end{itemize}
\end{small}
\end{frame}



\againframe{material}



\end{document}