mirror of
https://github.com/ThrowTheSwitch/CException
synced 2025-06-01 18:49:33 -04:00
262 lines
11 KiB
Plaintext
262 lines
11 KiB
Plaintext
====================================================================
|
|
CException
|
|
====================================================================
|
|
|
|
CException is a basic exception framework for C, suitable for use in
|
|
embedded applications. It provides an exception framework similar in
|
|
use to C++, but with much less overhead.
|
|
|
|
CException uses C standard library functions setjmp and longjmp to
|
|
operate. As long as the target system has these two functions defined,
|
|
this library should be useable with very little configuration. It
|
|
even supports environments where multiple program flows are in use,
|
|
such as real-time operating systems.
|
|
|
|
There are about a gabillion exception frameworks using a similar
|
|
setjmp/longjmp method out there... and there will probably be more
|
|
in the future. Unfortunately, when we started our last embedded
|
|
project, all those that existed either (a) did not support multiple
|
|
tasks (therefore multiple stacks) or (b) were way more complex than
|
|
we really wanted. CException was born.
|
|
|
|
Why use CException?
|
|
|
|
0. It's ANSI C, and it beats passing error codes around.
|
|
|
|
1. You want something simple... CException throws a single id. You can
|
|
define those ID's to be whatever you like. You might even choose which
|
|
type that number is for your project. But that's as far as it goes.
|
|
We weren't interested in passing objects or structs or strings...
|
|
just simple error codes.
|
|
|
|
2. Performance... CException can be configured for single tasking or
|
|
multitasking. In single tasking, there is very little overhead past
|
|
the setjmp/longjmp calls (which are already fast). In multitasking,
|
|
your only additional overhead is the time it takes you to determine
|
|
a unique task id 0 - num_tasks.
|
|
|
|
For the latest version, go to http://cexception.sourceforge.net
|
|
|
|
--------------------------------------------------------------------
|
|
CONTENTS OF THIS DOCUMENT
|
|
--------------------------------------------------------------------
|
|
|
|
Usage
|
|
Limitations
|
|
API
|
|
Configuration
|
|
Testing
|
|
License
|
|
|
|
--------------------------------------------------------------------
|
|
Usage
|
|
--------------------------------------------------------------------
|
|
|
|
Code that is to be protected are wrapped in Try { } Catch { } blocks.
|
|
The code directly following the Try call is "protected", meaning that
|
|
if any Throws occur, program control is directly transferred to the
|
|
start of the Catch block.
|
|
|
|
A numerical exception ID is included with Throw, and is made accessible
|
|
from the Catch block.
|
|
|
|
Throws can occur from within function calls (nested as deeply as you
|
|
like) or directly from within the function itself.
|
|
|
|
--------------------------------------------------------------------
|
|
Limitations
|
|
--------------------------------------------------------------------
|
|
|
|
This library was made to be as fast as possible, and provide basic
|
|
exception handling. It is not a full-blown exception library. Because
|
|
of this, there are a few limitations that should be observed in order
|
|
to successfully utilize this library:
|
|
|
|
1. Do not directly "return" from within a Try block, nor "goto"
|
|
into or out of a Try block.
|
|
|
|
Why?
|
|
|
|
The "Try" macro allocates some local memory and alters a global
|
|
pointer. These are cleaned up at the top of the "Catch" macro.
|
|
Gotos and returns would bypass some of these steps, resulting in
|
|
memory leaks or unpredictable behavior.
|
|
|
|
2. If (a) you change local (stack) variables within your Try block,
|
|
AND (b) wish to make use of the updated values after an exception
|
|
is thrown, those variables should be made volatile. Note that this
|
|
is ONLY for locals and ONLY when you need access to them after a
|
|
throw.
|
|
|
|
Why?
|
|
|
|
Compilers optimize. There is no way to guarantee that the actual
|
|
memory location was updated and not just a register unless the
|
|
variable is marked volatile.
|
|
|
|
3. Memory which is malloc'd or new'd is not automatically released
|
|
when an error is thrown. This will sometimes be desirable, and
|
|
othertimes may not. It will be the responsibility of the Catch
|
|
block to perform this kind of cleanup.
|
|
|
|
Why?
|
|
|
|
There's just no easy way to track malloc'd memory, etc., without
|
|
replacing or wrapping malloc calls or something like that. This
|
|
is a light framework, so these options were not desirable.
|
|
|
|
--------------------------------------------------------------------
|
|
API
|
|
--------------------------------------------------------------------
|
|
|
|
Try
|
|
---
|
|
|
|
Try is a macro which starts a protected block. It MUST be followed by
|
|
a pair of braces or a single protected line (similar to an 'if'),
|
|
enclosing the data that is to be protected. It MUST be followed by a
|
|
Catch block (don't worry, you'll get compiler errors to let you know if
|
|
you mess any of that up).
|
|
|
|
Catch(e)
|
|
--------
|
|
|
|
Catch is a macro which ends the Try block and starts the error handling
|
|
block. The catch block is called if and only if an exception was thrown
|
|
while within the Try block. This error was thrown by a Throw call
|
|
somewhere within Try (or within a function called within Try, or a function
|
|
called by a function called within Try, etc).
|
|
|
|
The single parameter 'e' is filled with the error code which was thrown.
|
|
This can be used for reporting, conditional cleanup, etc. (or you can just
|
|
ignore it if you really want... people ignore return codes all the time,
|
|
right?). 'e' should be of type EXCEPTION_T;
|
|
|
|
Throw(e)
|
|
--------
|
|
|
|
The method of throwing an error. Throws should only occur from within a
|
|
protected (Try...Catch) block, though it may easily be nested many function
|
|
calls deep without an impact on performance or functionality. Throw takes
|
|
a single argument, which is an exception id which will be passed to Catch
|
|
as the reason for the error.
|
|
|
|
If you wish to Rethrow an error, this can be done by calling Throw(e) with
|
|
the error code you just caught. It IS valid to throw from a catch block.
|
|
|
|
ExitTry()
|
|
---------
|
|
|
|
On rare occasion, you might want to immediately exit your current Try block
|
|
but NOT treat this as an error. Don't run the Catch. Just start executing
|
|
from after the Catch as if nothing had happened... That's what ExitTry is
|
|
for.
|
|
|
|
--------------------------------------------------------------------
|
|
CONFIGURATION
|
|
--------------------------------------------------------------------
|
|
|
|
CException is a mostly portable library. It has one universal
|
|
dependency, and some macros which are required if working in a
|
|
multi-tasking environment.
|
|
|
|
1. The standard C library setjmp must be available. Since this is part
|
|
of the standard library, chances are good that you'll be fine.
|
|
|
|
2. If working in a multitasking environment, methods for obtaining an
|
|
index into an array of frames and to get the overall number of
|
|
id's are required. If the OS supports a method to retrieve Task
|
|
ID's, and those Tasks are number 0, 1, 2... you are in an ideal
|
|
situation. Otherwise, a more creative mapping function may be
|
|
required. Note that this function is likely to be called twice
|
|
for each protected block and once during a throw. This is the
|
|
only overhead in the system.
|
|
|
|
Exception.h
|
|
-----------------
|
|
By convention, most projects include Exception.h which defines any
|
|
further requirements, then calls CException.h to do the gruntwork. All
|
|
of these are optional. You could directly include CException.h if
|
|
you wanted and just use the defaults provided.
|
|
|
|
EXCEPTION_T - Set this to the type you want your exception id's
|
|
to be. Defaults to 'unsigned int'.
|
|
|
|
EXCEPTION_NONE - Set this to a number which will never be an
|
|
exception id in your system. Defaults to 0x5a5a5a5a.
|
|
|
|
EXCEPTION_GET_ID - If in a multi-tasking environment, this should be
|
|
set to be a call to the function described in #2 above.
|
|
Defaults to just return 0 all the time (good for
|
|
single tasking environments)
|
|
|
|
EXCEPTION_NUM_ID - If in a multi-tasking environment, this should be set
|
|
to the number of ID's required (usually the number of
|
|
tasks in the system). Defaults to 1 (for single
|
|
tasking environments).
|
|
|
|
CEXCEPTION_NO_CATCH_HANDLER(id) - This macro can be optionally specified.
|
|
It allows you to specify code to be called when a Throw
|
|
is made outside of Try...Catch protection. Consider
|
|
this the emergency fallback plan for when something has
|
|
gone terribly wrong.
|
|
|
|
You may also want to include any header files which will commonly be
|
|
needed by the rest of your application where it uses exception handling
|
|
here. For example, OS header files or exception codes would be useful.
|
|
|
|
Finally, there are some hook macros which you can implement to inject
|
|
your own target-specific code in particular places. It is a rare instance
|
|
where you will need these, but they are here if you need them:
|
|
|
|
CEXCEPTION_HOOK_START_TRY - called immediately before the Try block
|
|
CEXCEPTION_HOOK_HAPPY_TRY - called immediately after the Try block
|
|
if no exception was thrown
|
|
CEXCEPTION_HOOK_AFTER_TRY - called immediately after the Try block
|
|
OR before an exception is caught
|
|
CEXCEPTION_HOOK_START_CATCH - called immediately before the catch
|
|
|
|
--------------------------------------------------------------------
|
|
TESTING
|
|
--------------------------------------------------------------------
|
|
|
|
If you want to validate that CException works with your tools or that
|
|
it works with your custom configuration, you may want to run the test
|
|
suite.
|
|
|
|
The test suite included makes use of the Unity Test Framework. It will
|
|
require a native C compiler. The example makefile uses MinGW's gcc.
|
|
Modify the makefile to include the proper paths to tools, then run 'make'
|
|
to compile and run the test application.
|
|
|
|
C_COMPILER - The C compiler to use to perform the tests
|
|
C_LIBS - The path to the C libraries (including setjmp)
|
|
UNITY_DIR - The path to the Unity framework (required to run tests)
|
|
(get it at http://unity.sourceforge.net)
|
|
|
|
--------------------------------------------------------------------
|
|
LICENSE
|
|
--------------------------------------------------------------------
|
|
|
|
This software is licensed under the MIT License
|
|
|
|
Copyright (c) 2007-2016 Mark VanderVoord
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
THE SOFTWARE.
|