[FFmpeg-devel] [RFC] Advanced Error Codes

[Michael Niedermayer]

Hi

People are asking for better error codes
Heres a quick pseodocode design / implementation / brainstorming:
I hope iam not re-doing some past one but i didnt quickly find a past discussion

Observations.
    Errors are for developers debuging or users resolving problems
    We rarely care about more then 2-3 independant errors but we care about their history like from where they came and how and what arguments caused them
    We also care about the error free case being fast, really fast
    We are lazy we dont want maintaince burden
    We also dont want to deal with maintaining matching cleanup for each generated error

Idea 1
    + very simple
    + fully compatible can be freely mixed with existing error codes
    - needs a global table
    + we never alloc, so we have no cleanup to do
    + zero overhead for passing around as its just integers

Idea 2 (Alternatrive)
    This is exactly like Idea 1 but using thread local instead of a global tabl
    + No mutex
    + no global table
    + no denial of service if a thread blasts errors out while another has an occasional error
    - Thread local table
    - More complex and slow to move errors accross thread boundaries

For both ideas:
* New error codes are 64bit
* if they are trunctaed to 32bit they are a valid 32bit error code like AVERROR(EIO)
* That means the new error codes are 32bit (existing error code for compatibility) and
  32bit (a identifier into a fixed size table.)


Pseudocode:

#define MAX_CONCURRENT_ERRORS 256   // error 256 will use slot 0, 257 slot 1 and so on
#define MASK (MAX_CONCURRENT_ERRORS - 1)

#define FREE_FORM_LEN 64 //probably we will need more, can just be bumped

typedef struct AdvancedError {
    const char *error_name;          ///< like "Timeout"       or  "Invalid Bitstream"
    const char *operation_name;      ///< like "Network Read"  or  "H.264 block parsing"
    const char *source_filename;     ///< like ffmpeg.c
    int source_line_number;          ///< like line 123 in ffmpeg.c
    char free_form_description[FREE_FORM_LEN];  ///< anything extra that doesnt fit in pointers to static const strings
    int64_t this_error;
    int64_t previous_error;          ///< A previous related error, if any
    int64_t timestamp;               ///< Timestamp at which the error occured
    int thread_id;
} AdvancedError;

struct AdvancedError   advanced_error[MAX_CONCURRENT_ERRORS];       // the whole is 32kb ATM

int64_t av_adv_err_new(int error_code,
                       const char *error_name,
                       const char *operation_name,
                       const char *source_filename,
                       int source_line_number,
                       int64_t previous_error,
                       const char free_form_description[FREE_FORM_LEN],
                       ) {
    pthread_mutex_lock()
        int64_t err = error_code + (counter++ << 32);
        AdvancedError *ae = &advanced_error[(err>>32) & MASK];
        ae->error_name         = error_name;
        ae->operation_name     = operation_name;
        ae->source_filename    = source_filename;
        ae->source_line_number = source_line_number;
        ae->this_error         = err;
        ae->previous_error     = previous_error;
        ae->timestamp          = av_gettime();
        memcpy(ae->free_form_description, free_form_description, FREE_FORM_LEN);
    pthread_mutex_unlock()

    return err;
}

/**
 * Retrieve AdvancedError struct for a given error code or fail
 * @param adv_err [OUT] where to store the AdvancedError in
 *
 * @return 0 on success negative on failure
 */
int av_adv_err_retrieve(int64_t err, AdvancedError *adv_err) {
    int ret = -1;

    pthread_mutex_lock()
        int index = err >> 32;
        if (advanced_error[index & MASK].this_error == err) {
            memcpy(adv_err, &advanced_error[index & MASK], sizeof(adv_err));
            ret = 0;
        }
    pthread_mutex_unlock()
    return ret;
}



-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

If you drop bombs on a foreign country and kill a hundred thousand
innocent people, expect your government to call the consequence
"unprovoked inhuman terrorist attacks" and use it to justify dropping
more bombs and killing more people. The technology changed, the idea is old.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20250702/13d64166/attachment.sig>