| Message ID | 1397593031-38578-2-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
On Tue, Apr 15, 2014 at 3:17 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > +@subsection run_time_examples Examples > +- Being "too late" to cancel a timer that's already popped, or exceeding some implementation-defined limit > +- Backpressure due to resource limits (corner case that is error-prone) > +- Checks for any condition that could arise in the field, e.g. running out of buffers or failure to allocate memory > +@code > + > +if (unrecoverable_out_of_foos == 1) > +{ > + ODP_ERR("Completely unable to proceed, no foos available"); > + tidy_op_for_exit(); > + ... > +} Shouldn't that be tidy_up_for_exit() ? Also, this code is reflecting some sort of a fatal condition, which doesn't match the above prose that implies a recoverable/deferrable condition. > +@section compile_run_time Run time programming exceptions > +There are two rules > +-# These must be capable of being turned off with -DNDEBUG > +-# They must use ODP_ASSERT so that the output may be redirected on systems without stderr. > + > +@subsection compile_run_time_examples Examples > +Checks that the API function arguments are within the permitted value range (e.g. handle validation > + > +@code > +void odp_foo(char *pointer) > +{ > + ODP_ASSERT(pointer != NULL); > + … > +} > +@endcode > +*/ By implication, ODP_ASSERT() expands to nothing when -DNDEBUG is specified?
On 15 April 2014 17:21, Bill Fischofer <bill.fischofer@linaro.org> wrote: > On Tue, Apr 15, 2014 at 3:17 PM, Mike Holmes <mike.holmes@linaro.org> > wrote: > > > +@subsection run_time_examples Examples > > +- Being "too late" to cancel a timer that's already popped, or > exceeding some implementation-defined limit > > +- Backpressure due to resource limits (corner case that is error-prone) > > +- Checks for any condition that could arise in the field, e.g. running > out of buffers or failure to allocate memory > > +@code > > + > > +if (unrecoverable_out_of_foos == 1) > > +{ > > + ODP_ERR("Completely unable to proceed, no foos available"); > > + tidy_op_for_exit(); > > + ... > > +} > > Shouldn't that be tidy_up_for_exit() ? Also, this code is reflecting > some sort of a fatal condition, which doesn't match the above prose > that implies a recoverable/deferrable condition. > I can change the example, but I thought it is a run time error that the > application should deal with as per the statement above it about running > out of memory. > In this case the application can perform some actions, maybe ask for a > smaller buffer and re call, so it is recoverable but not by the ODP > library, > > > +@section compile_run_time Run time programming exceptions > > +There are two rules > > +-# These must be capable of being turned off with -DNDEBUG > > +-# They must use ODP_ASSERT so that the output may be redirected on > systems without stderr. > > + > > +@subsection compile_run_time_examples Examples > > +Checks that the API function arguments are within the permitted value > range (e.g. handle validation > > + > > +@code > > +void odp_foo(char *pointer) > > +{ > > + ODP_ASSERT(pointer != NULL); > > + … > > +} > > +@endcode > > +*/ > > By implication, ODP_ASSERT() expands to nothing when -DNDEBUG is specified? > I think Ola suggested we make the enablement be ODP specific and I agree - how about -DNODP_DEBUG to disable debugging macros, by default debug is on as per regular assert ?
On 04/16/2014 03:26 AM, Mike Holmes wrote: > > > > > > On 15 April 2014 17:21, Bill Fischofer <bill.fischofer@linaro.org > <mailto:bill.fischofer@linaro.org>> wrote: > > On Tue, Apr 15, 2014 at 3:17 PM, Mike Holmes > <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: > > > +@subsection run_time_examples Examples > > +- Being "too late" to cancel a timer that's already popped, or > exceeding some implementation-defined limit > > +- Backpressure due to resource limits (corner case that is > error-prone) > > +- Checks for any condition that could arise in the field, e.g. > running out of buffers or failure to allocate memory > > +@code > > + > > +if (unrecoverable_out_of_foos == 1) > > +{ > > + ODP_ERR("Completely unable to proceed, no foos available"); > > + tidy_op_for_exit(); > > + ... > > +} > > Shouldn't that be tidy_up_for_exit() ? Also, this code is reflecting > some sort of a fatal condition, which doesn't match the above prose > that implies a recoverable/deferrable condition. > I can change the example, but I thought it is a run time error > that the application should deal with as per the statement above > it about running out of memory. > In this case the application can perform some actions, maybe ask > for a smaller buffer and re call, so it is recoverable but not by > the ODP library, > > > +@section compile_run_time Run time programming exceptions > > +There are two rules > > +-# These must be capable of being turned off with -DNDEBUG > > +-# They must use ODP_ASSERT so that the output may be > redirected on systems without stderr. > > + > > +@subsection compile_run_time_examples Examples > > +Checks that the API function arguments are within the permitted > value range (e.g. handle validation > > + > > +@code > > +void odp_foo(char *pointer) > > +{ > > + ODP_ASSERT(pointer != NULL); > > + … > > +} > > +@endcode > > +*/ > > By implication, ODP_ASSERT() expands to nothing when -DNDEBUG is > specified? > > I think Ola suggested we make the enablement be ODP specific and I > agree - how about -DNODP_DEBUG to disable debugging macros, by default > debug is on as per regular assert ? > in spite of assert() looks for NDEBUG I would vote for something more readable like ODP_ASSERT_ENABLE. Maxim. > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
+1 Switches shouldn't lead to head-scratching. Is it N for eNable? N for No? Something else we just have to know? Better to just say what we mean. Bill On Wed, Apr 16, 2014 at 6:44 AM, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > On 04/16/2014 03:26 AM, Mike Holmes wrote: >> >> >> >> >> >> >> On 15 April 2014 17:21, Bill Fischofer <bill.fischofer@linaro.org >> <mailto:bill.fischofer@linaro.org>> wrote: >> >> On Tue, Apr 15, 2014 at 3:17 PM, Mike Holmes >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: >> >> > +@subsection run_time_examples Examples >> > +- Being "too late" to cancel a timer that's already popped, or >> exceeding some implementation-defined limit >> > +- Backpressure due to resource limits (corner case that is >> error-prone) >> > +- Checks for any condition that could arise in the field, e.g. >> running out of buffers or failure to allocate memory >> > +@code >> > + >> > +if (unrecoverable_out_of_foos == 1) >> > +{ >> > + ODP_ERR("Completely unable to proceed, no foos available"); >> > + tidy_op_for_exit(); >> > + ... >> > +} >> >> Shouldn't that be tidy_up_for_exit() ? Also, this code is reflecting >> some sort of a fatal condition, which doesn't match the above prose >> that implies a recoverable/deferrable condition. >> I can change the example, but I thought it is a run time error >> that the application should deal with as per the statement above >> it about running out of memory. >> In this case the application can perform some actions, maybe ask >> for a smaller buffer and re call, so it is recoverable but not by >> the ODP library, >> >> > +@section compile_run_time Run time programming exceptions >> > +There are two rules >> > +-# These must be capable of being turned off with -DNDEBUG >> > +-# They must use ODP_ASSERT so that the output may be >> redirected on systems without stderr. >> > + >> > +@subsection compile_run_time_examples Examples >> > +Checks that the API function arguments are within the permitted >> value range (e.g. handle validation >> > + >> > +@code >> > +void odp_foo(char *pointer) >> > +{ >> > + ODP_ASSERT(pointer != NULL); >> > + … >> > +} >> > +@endcode >> > +*/ >> >> By implication, ODP_ASSERT() expands to nothing when -DNDEBUG is >> specified? >> >> I think Ola suggested we make the enablement be ODP specific and I agree - >> how about -DNODP_DEBUG to disable debugging macros, by default debug is on >> as per regular assert ? >> > in spite of assert() looks for NDEBUG I would vote for something more > readable like ODP_ASSERT_ENABLE. > > Maxim. >> >> >> >> -- >> *Mike Holmes* >> >> Linaro Technical Manager / Lead >> LNG - ODP >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp > > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
diff --git a/exception_handling.dox b/exception_handling.dox new file mode 100644 index 0000000..d03d87a --- /dev/null +++ b/exception_handling.dox @@ -0,0 +1,115 @@ +/* +Copyright (c) 2014, Linaro Limited +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + + * 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. + + * Neither the name of Linaro Limited 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 HOLDER 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. +*/ + +/** +@page exception_handling Exception handling in the ODP API +@tableofcontents + +For the implimentation of the exception handling please see @ref odp_debug.h + +@section requirements Requirements +- Minimal overhead in a finished running system. +- Minimizing the propagation of an error from its point of origin +- Identifying what is a programming error +- Identifying a legitimate infield exception +- We only specify what happens inside the ODP library, not in a calling application + +There are two kinds of exceptional behaviour, +-# Run time exceptions, those that are unusual but foreseeable cases in a running system (out of memory) +-# Programming exceptions, those introduced as bugs (null pointers, out of bounds). + +@section run_time Run time exceptions +These are characterized by the following rules in order of importance +-# These must gracefully leave the system in a known stable state. +-# These checks must remain unconditionally in the code base. +-# These should return the error state to the caller. +-# They may emit an error message via \ref ODP_ERR which can be redefined or disabled. + +@subsection run_time_examples Examples +- Being "too late" to cancel a timer that's already popped, or exceeding some implementation-defined limit +- Backpressure due to resource limits (corner case that is error-prone) +- Checks for any condition that could arise in the field, e.g. running out of buffers or failure to allocate memory +@code + +if (unrecoverable_out_of_foos == 1) +{ + ODP_ERR("Completely unable to proceed, no foos available"); + tidy_op_for_exit(); + ... +} + +@endcode +@note ODP does not trap segfaults, it may not be checking for NULL pointers etc to improve the execution speed. The application should trap segfaults. + +@section programming_exceptions Programming exceptions +There are two classes of programming error +-# Compile time, these can be caught by compile time assertions in the preprocessor +-# Run Time, these are run time assertions + +@section compile_time Compile time programming exceptions +These have the following rules +-# Zero overhead at run time, they never need to be turned off (undefined) +-# Use @#error which will break the build, or @#warning which may not break the build unless -Werror is defined. +-# Can be done for any static evaluation case. + +@subsection compile_time_examples Examples +Checking size and alignment of a struct with offsetof + +@code +typedef struct timer timer;} +struct timer +{ + uint8_t MODE; + uint32_t DATA; + uint32_t COUNT; +}; + + +#if (offsetof(timer, DATA) != 4)} +#error DATA must be at offset 4 in timer +#endif +@endcode + +@section compile_run_time Run time programming exceptions +There are two rules +-# These must be capable of being turned off with -DNDEBUG +-# They must use ODP_ASSERT so that the output may be redirected on systems without stderr. + +@subsection compile_run_time_examples Examples +Checks that the API function arguments are within the permitted value range (e.g. handle validation + +@code +void odp_foo(char *pointer) +{ + ODP_ASSERT(pointer != NULL); + … +} +@endcode +*/
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- exception_handling.dox | 115 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 exception_handling.dox