CException - Lightweight exception library for C
================================================
[![CException Build Status](https://api.travis-ci.org/ThrowTheSwitch/CException.png?branch=master)](https://travis-ci.org/ThrowTheSwitch/CException)
_This Documentation Is Released Under a Creative Commons 3.0 Attribution Share-Alike License_
CException is simple exception handling in C. It is significantly faster than full-blown C++ exception handling
but loses some flexibility. It is portable to any platform supporting `setjmp`/`longjmp`.
Getting Started
================
The simplest way to get started is to just grab the code and pull it into your project:
```
git clone https://github.com/throwtheswitch/cexception.git
```
If you want to contribute to this project, you'll also need to have Ruby and Ceedling installed to run the unit tests.
Usage
=====
### So what's it good for?
Mostly error handling. Passing errors down a long chain of function calls gets ugly. Sometimes really ugly.
So what if you could just specify certain places where you want to handle errors, and all your errors were
transferred there? Let's try a lame example:
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...
we started this project for use in embedded systems... but it obviously can be used for larger systems too.
### Error Handling with CException:
```
void functionC(void) {
//do some stuff
if (there_was_a_problem)
Throw(ERR_BAD_BREATH);
//this stuff never gets called because of error
}
```
There are about a gajillion 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?
====
### It's ANSI C
...and it beats passing error codes around.
### 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. Fast. Easy to Use. Easy to Understand.
### 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 to num_tasks).
How?
====
Code that is to be protected are wrapped in `Try { }` blocks. The code inside the Try block is _protected_,
meaning that if any Throws occur, program control is directly transferred to the start of the Catch block.
The Catch block immediately follows the Try block. It's ignored if no errors have occurred.
A numerical exception ID is included with Throw, and is passed into the Catch block. This allows you to handle
errors differently or to report which error has occurred... or maybe it just makes debugging easier so you
know where the problem was Thrown.
Throws can occur from anywhere inside the Try block, directly in the function you're testing or even within
function calls (nested as deeply as you like). There can be as many Throws as you like, just remember that
execution of the guts of your Try block ends as soon as the first Throw is triggered. Once you throw, you're
transferred to the Catch block. A silly example:
```
void SillyExampleWhichPrintsZeroThroughFive(void) {
CEXCEPTION_T e;
int i;
while (i = 0; i < 6; i++) {
Try {
Throw(i);
//This spot is never reached
}
Catch(e) {
printf(“%i “, e);
}
}
}
```
Limitations
===========
This library was made to be as fast as possible, and provide basic exception handling. It is not a full-blown
exception library like C++. Because of this, there are a few limitations that should be observed in order to
successfully utilize this library:
### Return & Goto
Do not directly `return` from within a `Try` block, nor `goto` into or out of a `Try` block.
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.
### Local Variables
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`.
Compilers optimize (and thank goodness they do). There is no way to guarantee that the actual memory
location was updated and not just a register unless the variable is marked volatile.
### Memory Management
Memory which is `malloc`'d within a `Try` block 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 code you put in
the `Catch` block to perform this kind of cleanup.
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 lightweight framework, so these options were not desirable.
CException 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).
The `Try` block is your protected block. It contains your main program flow, where you can ignore errors
(other than a quick `Throw` call). You may nest multiple `Try` blocks if you want to handle errors at
multiple levels, and you can even rethrow an error from within a nested `Catch`.
### `Catch(e) { }`
`Catch` is a macro which ends the `Try` block and starts the error handling block. The `Catch` block
is executed 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`... you get the idea.).
`Catch` receives a single id of type `CEXCEPTION_T` which you can ignore or use to handle the error in
some way. You may throw errors from within Catches, but they will be caught by a `Try` wrapping the `Catch`,
not the one immediately preceeding.
### `Throw(e)`
`Throw` is the method used to throw an error. `Throw`s 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 _re-throw_ 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()`
`ExitTry` is a method used 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.
Configuration
=============
CException is a mostly portable library. It has one universal dependency, plus some macros which are required if
working in a multi-tasking environment.
The standard C library setjmp must be available. Since this is part of the standard library, it's al
没有合适的资源?快使用搜索试试~ 我知道了~
资源详情
资源评论
资源推荐
收起资源包目录
stm32F103的FreeRTOS简单文件夹,keil5版本 (1405个子文件)
RTOSDemo.uvguix.19685 89KB
RTOSDemo.axf 317KB
RTOSDemo_sct.Bak 479B
BasicInterrupt_SAM7X.cspy.bat 3KB
cmock_demo.cspy.bat 3KB
cmock_demo.cspy.bat 2KB
meson.build 2KB
meson.build 2KB
meson.build 544B
meson.build 539B
meson.build 459B
meson.build 313B
meson.build 286B
meson.build 276B
meson.build 260B
meson.build 159B
build-html-doc 2KB
tasks.c 221KB
stm32fxxx_eth.c 138KB
queue.c 123KB
stm32f10x_tim1.c 107KB
stm32f10x_tim1.c 107KB
mib2.c 103KB
mib2.c 102KB
stm32f10x_tim.c 92KB
stm32f10x_tim.c 92KB
test_unity_arrays.c 74KB
sockets.c 68KB
unity.c 64KB
dhcp.c 63KB
test_unity_integers.c 62KB
StreamBufferDemo.c 60KB
TaskNotifyArray.c 57KB
tcp_in.c 57KB
ppp.c 57KB
lcp.c 56KB
stream_buffer_utest.c 56KB
dhcp.c 54KB
stm32f10x_adc.c 53KB
stm32f10x_adc.c 53KB
lcp.c 52KB
lcd.c 52KB
lcd.c 52KB
stream_buffer.c 52KB
timers.c 49KB
ppp.c 49KB
tcp.c 49KB
tcp_out.c 48KB
StaticAllocation.c 48KB
etharp.c 47KB
TimerDemo.c 47KB
QueueSet.c 46KB
MessageBufferDemo.c 45KB
api_msg.c 44KB
tcp_in.c 44KB
stm32f10x_i2c.c 44KB
stm32f10x_i2c.c 44KB
msg_in.c 43KB
msg_in.c 42KB
stm32f10x_rcc.c 41KB
stm32f10x_rcc.c 41KB
EventGroupsDemo.c 40KB
GenQTest.c 38KB
ipcp.c 38KB
pbuf.c 37KB
sockets.c 37KB
ipcp.c 36KB
auth.c 35KB
queue_send_nonblocking_utest.c 35KB
queue_send_nonblocking_utest.c 35KB
queue_receive_nonblocking_utest.c 34KB
queue_receive_nonblocking_utest.c 34KB
stm32f10x_fsmc.c 34KB
list_utest.c 33KB
ppp_oe.c 33KB
stm32f10x_usart.c 33KB
stm32f10x_usart.c 33KB
pbuf.c 33KB
queue_in_set_utest.c 32KB
tcp.c 32KB
etharp.c 32KB
udp.c 32KB
event_groups.c 31KB
IntQueue.c 31KB
message_buffer_utest.c 30KB
dns.c 30KB
mib_structs.c 30KB
ip.c 30KB
stm32f10x_can.c 30KB
stm32f10x_can.c 30KB
TaskNotify.c 30KB
AbortDelay.c 30KB
port.c 30KB
binary_semaphore_utest.c 29KB
binary_semaphore_utest.c 29KB
mib_structs.c 29KB
stm32f10x_nvic.c 28KB
stm32f10x_nvic.c 28KB
ip_frag.c 28KB
event_groups_utest.c 28KB
共 1405 条
- 1
- 2
- 3
- 4
- 5
- 6
- 15
风正豪
- 粉丝: 3w+
- 资源: 8
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功
评论0