API design question

Discussion in 'C Programming' started by andrew queisser, Feb 21, 2006.

  1. Hi all,

    I'm working on a small embedded system (think microcontroller with uC/OS-II)
    and I'm considering which convention to use for error handling in our
    internal "API". Since I'm using two existing APIs (a low-level HAL and the
    OS API) I already have mixed conventions since some return 0 for failure,
    some return 0 for "no-error", etc.

    I'm leaning toward the following basic rules, please critique at will:

    1) Functions return what's convenient instead of forcing into a common
    return-code convention. I don't like to have to write two lines of code
    instead of one when testing return codes.

    a) Boolean functions return 1/0, therefore boolean functions are not allowed
    to fail
    b) I/O functions return number of bytes read/written. Return of zero
    indicates end-of-file, negative return indicates error
    c) Functions that can fail and return a value that can be positive, negative
    or zero have to return the error via pointer-to-argument. That allows
    putting the function call into an if-statement when looking for a specific
    return value

    2) Keep a global header file with a list of error codes (a la winerror.h).
    OS and HAL error codes get mapped to our global error codes as needed.

    a) all error codes are negative
    b) error codes are scalar (no bitfields), multiple concurrent error codes
    have to be resolved by a separate mechanism

    3) Have a global error code that can be returned via global function (a la
    GetLastError()).

    a) successful completion of a function (generally) does not overwrite last
    error
    b) last error is kept per thread


    Comments? Suggestions?

    Thanks,
    Andrew
    andrew queisser, Feb 21, 2006
    #1
    1. Advertising

  2. andrew queisser

    Malcolm Guest

    "andrew queisser" <andrew.queisser at hp com> wrote
    >
    > I'm working on a small embedded system (think microcontroller with
    > uC/OS-II) and I'm considering which convention to use for error handling
    > in our internal "API". Since I'm using two existing APIs (a low-level HAL
    > and the OS API) I already have mixed conventions since some return 0 for
    > failure, some return 0 for "no-error", etc.
    >
    > Comments? Suggestions?
    >

    There is no easy solution tot he problem of errors.

    You need one type when debugging, another type when distributing beta type
    code to users, and a third type when you know the code itself is robust but
    input may not be.

    Sometimes you want code to be reusable, and sometimes you wnat a centralised
    list of error codes. You can't have both.

    One mistake the designer of the standard libary made was not to have any way
    of querying the line number of an input file from its file pointer.
    That would be one recommendation if you are doing IO from scratch,
    preseuming your input is text which could potentially be corrupted.
    --
    Buy my book 12 Common Atheist Arguments (refuted)
    $1.25 download or $6.90 paper, available www.lulu.com
    Malcolm, Feb 21, 2006
    #2
    1. Advertising

  3. In article <dtg3vm$akp$-infra.bt.com>,
    Malcolm <> wrote:
    >One mistake the designer of the standard libary made was not to have any way
    >of querying the line number of an input file from its file pointer.
    >That would be one recommendation if you are doing IO from scratch,
    >preseuming your input is text which could potentially be corrupted.


    hmmm, the number of times I've needed the input line number in a C program
    is... ummm, small enough that I'm having a hard time recalling any
    instances.

    I've needed the input line number a number of times in perl, awk, ed and
    sed, but very rarely in C.

    What kind of programs do you find that this feature would be
    a noticable advantage in? Is it mostly a matter of wanting reusable
    code that doesn't have to know how the rest of the program is
    keeping track of the line numbers ?
    --
    Programming is what happens while you're busy making other plans.
    Walter Roberson, Feb 22, 2006
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Scott

    API Design Question

    Scott, Jul 12, 2003, in forum: Java
    Replies:
    4
    Views:
    356
    Scott
    Jul 14, 2003
  2. Marcel Müller
    Replies:
    4
    Views:
    1,006
    Öö Tiib
    Jan 1, 2011
  3. Adam Skutt
    Replies:
    1
    Views:
    506
    Marcel Müller
    Jan 1, 2011
  4. Adam Skutt
    Replies:
    2
    Views:
    700
    Adam Skutt
    Jan 1, 2011
  5. Ethan Furman

    API design question for dbf.py

    Ethan Furman, Jul 6, 2012, in forum: Python
    Replies:
    0
    Views:
    157
    Ethan Furman
    Jul 6, 2012
Loading...

Share This Page