UT/UT_Interrupt.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:
 *      Paul Breslin
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        UT_Interrupt.h (C++)
 *
 * COMMENTS:
 *
 */

#ifndef __UT_Interrupt__
#define __UT_Interrupt__

#include "UT_API.h"

#include <sys/types.h>
#include "UT_String.h"
#include "UT_PtrArray.h"
#include "UT_RefArray.h"
#include "UT_Signal.h"
#include "UT_SysClone.h"

#include "UT_Lock.h"
#ifndef GAMEOS
    #include "UT_SharedMem.h"
#endif
        
class ut_IserverInterface;
class ut_Iclient;
class UT_Interrupt;

typedef void    (*UT_InterruptCB)(UT_Interrupt *me, int state, const char *op);
typedef void    (*OPUI_UpdateModeCB)();
typedef bool    (*UI_CheckForEscapeCB)();

class UT_API UT_InterruptHandler
{
public:
    virtual ~UT_InterruptHandler() {}
    virtual void        start(UT_Interrupt *intr,
                              const char *optext,
                              const char *main_op_text) =0;
    virtual void        push(const char *text) =0;
    virtual void        busyCheck(bool interrupted,
                                  float percent,
                                  float longpercent) = 0;
    virtual void        pop() =0;
    virtual void        stop() =0;

    virtual void        interruptAllowed(bool allowed, bool allow_ui) =0;
};

//
// These state values are passed to the active callback:
//
enum
{
    ACTIVE_STOP,                // Final opEnd
    ACTIVE_START,               // First opStart
    ACTIVE_PUSH,                // opStart
    ACTIVE_POP,                 // opEnd
    ACTIVE_BUSY,                // opInterrupt
    ACTIVE_ALLOW_CHANGE         // myInterruptable has changed state
};


#ifdef GAMEOS
class UT_API UT_Interrupt
#else
class UT_API UT_Interrupt : protected UT_SharedMem
#endif
{
public:
    explicit UT_Interrupt(const char *app_title = 0);
    virtual ~UT_Interrupt();

    // The interrupt object must be enabled for interrupts to be
    // allowed. The initial state is disabled.
    // If print_longtext is 1, then each time the "long" text is changed
    // with setLongOpText(), the text will be printed onto stdout.
    void        setEnabled(int state, int print_longtext = 0);
    bool        isEnabled() const { return (bool) myEnableFlag; }

    // If this class is being used in a single-threaded app then call
    // setUseLocks(0); Default is 1.
    void        setUseLocks(int state) { myUseLockFlag = (state != 0); }

    // If this flag is set to false, the idialog is started in uninterruptable
    // mode. This makes idialog basically a status display. Also, on threaded
    // UI, hitting ESC will do nothing.
    //
    // setInterruptable(true) returns false if UT_Interrupt was already
    // interrupted, and hence will fail to turn off the interruptable flag. If
    // prev_enabled is non-NULL, then it is set to the previous flag state,
    // regardless of the return value.
    // NB: setInterruptable() will perform locking using myInterruptableLock.
    bool        setInterruptable(bool allow, bool *prev_enabled = NULL,
                                 bool allow_ui = false);
    bool        getInterruptable() const        { return myInterruptable; }
    UT_Lock &   getInterruptableLock()          { return myInterruptableLock; }
    bool        getAllowUI() const              { return myAllowUI; }

    // To use the long operation mechanism invoke "opStart" once,
    // giving the name of the operation and (if possible) an estimate
    // of the number of calls which are planned to be made to the
    // opInterrup method. The start method will return zero if the
    // operation has already been terminated (possibly from a containing long
    // operation) and should not even start. In that case, you *must* still
    // call opEnd(). It will return one if the operation can proceed normally.
    //
    // During the long operation, invoke the "opInterrupt" method
    // (if possible, giving a value between 0 and 100 indicating the
    // percentage of the operation that is complete). This method will
    // return zero if the operation should continue and one if a request
    // was made to terminate. When the operation is complete, invoke the
    // "opEnd" method. This should be called even if the operation was
    // interrupted.
    //
    // The 'immediate_dialog' flag causes the idialog program to be started
    // immediately instead of waiting for a timeout. This is the only way to
    // start the idialog progress monitor, and should only be used for very
    // long operations where the user would minimize Houdini (like rendering)
    //
    // The opid can be used to verify nesting of interrupts.  It can be
    // passed to opEnd to verify that the nesting is proper...
    //
    // These methods are now thread safe. Only the main thread will start
    // the interrupt server. 
    int          opStart(const char *opname = 0, int npoll = 0,
                         int immediate_dialog=0, int *opid=0);
    int          opInterrupt(int percent = -1);

    void         opEnd(int opid=-1);

    // Call this before a new set of opStart()s are called. It will also 
    // cause idialog to configure the user interface with two text boxes
    // instead of the usual single line. After that, you can call
    // setLongOpText() to modify the second line message.
    void         setLongOpText(const char *longoptext);
    void         setLongPercent(float percent);

    // The application title string will be placed in the percent
    // completion dialog.
    void         setAppTitle(const char *title);
    const char  *getAppTitle() const { return myAppTitle; }

    // The active callback is invoked whenever opStart and opEnd are called.
    // This lets someone else keep track of when we're inside an interruptible
    // loop. The Interrupt Handler is similar but C++ based, and takes
    // precendence over the active callback 
    void         setActiveCallback(UT_InterruptCB function)
                 { myActiveCallback = function; }
    
    void         setInterruptHandler(UT_InterruptHandler *hand)
                 {
                     myUIHandler = hand;
                     if(hand)
                         hand->interruptAllowed(myInterruptable, myAllowUI);
                 }
    UT_InterruptHandler *getInterruptHandler() { return myUIHandler; }

    // Set the 'ourMemoryThresholdCallback' ptr to 'function'. See the
    // declaration of ourMemoryThresholdCallback for more details.
    static void  setUpdateModeCallback(OPUI_UpdateModeCB function)
                 { ourMemoryThresholdCallback  = function; }
    
    // Set the 'ourEscapeCheckCallback' ptr to 'function'.  See the 
    // declaration of ourEscapeCheckCallback for more details
    static void  setEscapeCheckCallback(UI_CheckForEscapeCB function)
                 { ourEscapeCheckCallback  = function; }
    static bool  getIsEscapeCheckCallbackSet()
                 { return ourEscapeCheckCallback; }
    
    // The interrupt callbacks are called when the user interrupts Houdini.
    // Add an interrupt callback when the operation being called needs to
    // do extra work to interrupt the main thread.  For example, to stop
    // python execution, an interrupt callback is needed to raise a python
    // exception.
    //
    // Only the callback that was pushed last will be called.
    void         pushInterruptCallback(void (*callback)());
    void         popInterruptCallback();

    // You can manually interrupt an active loop by calling this method.
    // If calling from a thread other than the looping thread then set
    // the use_semaphore flag.
    void         interrupt(int use_semaphore = 0);

    void         pause(bool dopause);

    bool         isPaused() const;

    // This is the signal handler that gets used when we're not in an
    // interruptable state.
    void         setSignalCallback(UTsigHandler function);

    // test if we're within the memory threshold, and if not, return true.
    bool         testMemoryThreshold()
                 {
                     return ourMemoryThresholdCallback
                                ?  doTestMemoryThreshold() : false;
                 }
protected:
    // These methods are used by the interrupt server to get access
    // to the shared memory segment.
    const char          *getSharedKey() const;

    virtual int          detach();

#ifdef GAMEOS
    void        *getMemory(int reuse=1) { return 0; }
    void         destroy()      {}
    int          setKey(const char *, int id=0) { return -1; }
    int          setKey(key_t key)      { return -1; }
    int          setSize(int size)      { return size; }
    UT_String    ourKeyPath;
#endif

private:
    bool                 doTestMemoryThreshold();
    void                 testIdialogInterrupt();
    void                 testEscCallbackInterrupt();

    void                 updateTitle(const char *);
    void                 operationComplete();
    void                 startServer();
    void                 stopServer();
    const char          *getOpName() const;
    void                 callInterruptCB();


    UT_PtrArray<const char *> myOpNameStack;

    UT_RefArray<void(*)()> myInterruptCBStack;

    UT_String            myAppTitle;
    UT_String            myLongOpText;
    UT_InterruptCB       myActiveCallback;
    UT_InterruptHandler *myUIHandler;
    char                *myServerPath;
    char                 myPidString[16];
    const char          *myArgv[16];
    int                  myOpDepth;
    UT_Interrupt        *myPreviousInterrupt;
    UT_Signal           *mySignal;
    UT_Signal           *mySignalSubstitute;
    UTsigHandler         mySignalCallback;
    pid_t                myServerPID;

    int                  myStartTime;

    short                myEnableFlag;
    short                myStartedFlag;
    short                myInterruptedFlag;
    char                 myPrintLongTextFlag;
    char                 myUseLockFlag;
    bool                 myInterruptable;
    bool                 myAllowUI;
    float                myPercent;
    float                myLongPercent;
    volatile bool        myPaused;

    // This is how we let OPUI_App know we'd like to change the update mode
    // to OPUI_UPDATE_ON_DEMAND when we're running out of virtual addresses
    static OPUI_UpdateModeCB     ourMemoryThresholdCallback;
    
    // This is how we ask the UI layer to check whether an escape key has
    // been pressed in the case where we do not have threaded UI.
    static UI_CheckForEscapeCB   ourEscapeCheckCallback;

    UT_Lock              myLock;
    UT_Lock              myInterruptableLock;

    static void          ut_interruptHandler(UTsignalHandlerArg);
};

UT_API extern UT_Interrupt      *UTgetInterrupt(); // Get the app interrupt ptr
UT_API extern void               UTsetInterrupt(UT_Interrupt *);

// a template for the comm layout for the shared memory link between
// UT_Interrupt and idialog.
class UT_API ut_InterruptTransactionData
{
public:                                 // I/O is relative to UT_Interrupt.
    volatile int   myCommand;           // In: 0 none, 1 interrupt, 2 pause
    volatile float myPercent;           // Out: current task % complete
    volatile float myLongPercent;       // Out: primary task % complete
    volatile int   myNumMessages;       // Out: # of messages in message area
    volatile char  myMessage[128];      // Out: message
    volatile char  myLongMessage[128];  // Out: message for long ops
};

// A simple client which can be used in processes spawned by Houdini (such
// as mantra). It allows these processes to report the completion percentage,
// and read the interrupt/pause state.
#ifdef GAMEOS
class UT_API UT_InterruptClient
#else
class UT_API UT_InterruptClient : public UT_SharedMem
#endif
{
public:
    UT_InterruptClient(pid_t server_id);
    ~UT_InterruptClient();

    bool        isInterrupted();
    
    void        setPercent(float p);
    void        setLongPercent(float p);

    void        setMessage(const char *title);

#ifdef GAMEOS
    void        *getMemory(int reuse=1) { return 0; }
    void         destroy()      {}
    int          setKey(const char *, int id=0) { return -1; }
    int          setKey(key_t key)      { return -1; }
    int          setSize(int size)      { return size; }
    UT_String    ourKeyPath;
#endif

};

// This helper class will make sure opEnd() is always called, even if you
// return early from a function.  It's similar to UT_AutoUndo.
class UT_API UT_AutoInterrupt
{
public:
    UT_AutoInterrupt(const char* operation_name,
                     UT_Interrupt *boss=UTgetInterrupt())
    : myInterrupt(boss)
    {
        myRunOk = myInterrupt ? (bool)myInterrupt->opStart(operation_name)
                              : true;
    }

    ~UT_AutoInterrupt()
    {
        if (myInterrupt)
            myInterrupt->opEnd();
    }

    bool wasInterrupted()
    {
        if (myRunOk && myInterrupt && myInterrupt->opInterrupt())
            myRunOk = false;
        return !myRunOk;
    }

    UT_Interrupt        *getInterrupt() const   { return myInterrupt; }

private:
    UT_Interrupt        *myInterrupt;
    bool                 myRunOk;
};

#endif /* __UT_Interrupt__ */

---