UT/UT_Exit.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Mark Elendt
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_Exit.h ( UT Library, C++)
 *
 * COMMENTS:    General exit mechanism...  This allows a list of callback
 *              functions to be added when exit is being called
 *              The callbacks are called in the order that they were added.
 *              The callback function will only be added once (even if the data
 *              is different).
 */

#ifndef __UT_Exit__
#define __UT_Exit__

#include "UT_API.h"

class UT_API UT_Exit {
public:
    // The enumeration of the exit codes that Houdini producs can use.
    // (see notes in http://tldp.org/LDP/abs/html/exitcodes.html)
    // NOTE: the numeric values for the specific exit reasons should not change:
    //       some customers explicitly test the numeric value of the exit code
    //       and take a specific action based on it. E.g., they may test the
    //       exit code for the license failure on a render farm for
    //       re-submission, but if we change the exit code for license failure
    //       their scripts will need to be updated to account for that.
    // NOTE: don't use exit code value of 259. On Windows, the exit code 259 
    //       means STILL_ACTIVE, and should not be used as an exit error code;
    //       otherwise the return value of GetExitCodeProcess() calls may be
    //       misinterpreted.
    enum UT_ExitCode
    {
        // no error
        EXIT_OK                 = 0,    

        // catch-all error code
        EXIT_GENERIC_ERROR      = 1,

        // misuse of shell builtins (according to Bash documentation)
        EXIT_BUILTIN_ERROR      = 2,    
        
        // failure to check out or verify an appropriate product license
        EXIT_LICENSE_ERROR      = 3,

        // socket communication failure
        EXIT_SOCKET_ERROR       = 4,

        // failed to parse the UI definition file
        EXIT_PARSE_UI_ERROR     = 5
    };

    // Calls exit(), which implicitly leads to our callbacks being called.
    static void         exit( UT_ExitCode exit_code = EXIT_OK );

    // Just like exit(), except sets the exit code to the properly offset
    // signal number according to the convention: 128 + signal_number.
    static void         exitWithSignalNumber( int signal_number );

    // An exit method that takes any exit code (as integer). Should be used
    // sparignly and only if necessary.  We want the exit codes to be
    // consistent, stable and well-known to the customers (we can document 
    // based on the above enum), so use exit() with UT_ExitCode, if possible.
    static void         exitWithSpecificCode( int exit_code );

    // Calls our callbacks directly, without calling exit(). This should
    // only be used by our core dump handler.
    static void         runExitCallbacks();

    // Returns 1 if the function was added, the function can only be added one
    // time. Returns 0 if this is a duplicate.
    static int          addExitCallback(void (*exitcallback)(void *data),
                                        void *data = 0);
    // Returns 1 if the function was removed. Returns 0 if the function was
    // never added.
    static int          removeExitCallback(void (*exitcallback)(void *data),
                                           void *data = 0);

    // Remove all the exit callbacks.
    static void         removeAllExitCallbacks();
};

#endif

---