threadSupport.h

Go to the documentation of this file.

/* Thread support for ROSE */
#ifndef ROSE_threadSupport_H
#define ROSE_threadSupport_H

/* Design rules:
 *   1. All public symbols in this file should use the "RTS_" prefix (ROSE Thread Support).
 *
 *   2. All constructs that have a user-supplied compound statement as a "body", have a matching "_END" macro.  For instance,
 *      RTS_MUTEX starts a mutual exclusion for a critical section, which ends with an RTS_MUTEX_END macro.  The END macros
 *      generally take no arguments.
 *
 *   3. Locally scoped symbols defined by the macros have names beginning with "RTS_". This is generally followed by the first
 *      letter of the rest of the macro name, a letter "s" or "p" for "shared" or "private", and an underscore.  For example,
 *      within the RTS_MUTEX macros, a private (non-shared) variable might be named "RTS_Mp_mutex".
 *
 *   4. Constructs that allow a user-supplied compound statement as a "body" should allow the body to "break" or "throw". Both
 *      forms of premature exit should behave as if the body executed to completion (except throw will throw the exception
 *      again automatically).
 *
 *   5. New functionality shall have types, constants, and functions reminiscent of the POSIX threads interface, but whose
 *      names begin with "RTS_" rather than "pthread_".
 */

/* Needed for ROSE_HAVE_PTHREAD_H definition */
#include "rosePublicConfig.h"

#include <assert.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>

#include <string>

/* Figure out whether ROSE can support multi-threading and what kind of support library is available. */
#ifdef ROSE_HAVE_PTHREAD_H
#  define ROSE_THREADS_ENABLED
#  define ROSE_THREADS_POSIX
#  include <pthread.h>
#else
#  undef  ROSE_THREADS_ENABLED
#endif

/* This warning is in a public header file so that end users will see it when they compile against a version of ROSE that
 * doesn't have multi-thread support.  It would be imprudent to move this to one of the library's *.C files because then
 * an end user might spend substantial time trying to figure out why his multi-threaded program fails nondeterministically when
 * the ROSE documentation advertises that certain functions are thread safe.
 *
 * Unfortunately, due to the way ROSE's header files are organized, threadSupport.h will be included by pretty much every
 * ROSE library source file because every file includes _all_ the Sage node definitions (instead of only the ones it needs),
 * and a few of those nodes (e.g., SgFile) depend on something defined by the Disassembler class. The Disassembler supports
 * multi threading and therefore includes this header. Therefore every ROSE library source file will spit out this warning. */
#ifndef ROSE_THREADS_ENABLED
#  ifdef _MSC_VER
#    pragma message("Multi-thread support is not enabled. ROSE will not be thread safe even for functions that advertise safety.")
#  else
#    warning "Multi-thread support is not enabled. ROSE will not be thread safe even for functions that advertise safety."
#  endif
#endif


/******************************************************************************************************************************
 *                                      Layered Synchronization Primitives
 ******************************************************************************************************************************/

enum RTS_Layer {
    RTS_LAYER_DONTCARE = 0,

    /* ROSE library layers, 100-199 */
    RTS_LAYER_ROSE_CALLBACKS_LIST_OBJ   = 100,          
    RTS_LAYER_RTS_MESSAGE_CLASS         = 105,          
    RTS_LAYER_DISASSEMBLER_CLASS        = 110,          
    /* Simulator layers (see projects/simulator), 200-220
     *
     * Constraints:
     *     RSIM_PROCESS_OBJ        < RSIM_PROCESS_CLONE_OBJ
     *     RSIM_SIGNALHANDLING_OBJ < RSIM_PROCESS_OBJ
     */
    RTS_LAYER_RSIM_SIGNALHANDLING_OBJ   = 200,          
    RTS_LAYER_RSIM_PROCESS_OBJ          = 201,          
    RTS_LAYER_RSIM_PROCESS_CLONE_OBJ    = 202,          
    RTS_LAYER_RSIM_THREAD_OBJ           = 203,          
    RTS_LAYER_RSIM_THREAD_CLASS         = 204,          
    RTS_LAYER_RSIM_SYSCALLDISABLER_OBJ  = 205,          
    RTS_LAYER_RSIM_TRACEIO_OBJ          = 206,          
    RTS_LAYER_RSIM_SIMULATOR_CLASS      = 207,          
    RTS_LAYER_RSIM_SIMULATOR_OBJ        = 208,          
    /* User layers.  These are for people that might want to use the ROSE Thread Support outside ROSE, such as in ROSE
     * projects.   We leave it up to them to organize how they'll use the available layers. */
    RTS_LAYER_USER_MIN                  = 250,          
    RTS_LAYER_USER_MAX                  = 299,          
    /* Max number of layers (i.e., 0 through N-1) */
    RTS_LAYER_NLAYERS                   = 300
};

bool RTS_acquiring(RTS_Layer);

void RTS_releasing(RTS_Layer);

/******************************************************************************************************************************
 *                                      Paired macros for using mutual exclusion locks
 ******************************************************************************************************************************/

#ifdef ROSE_THREADS_ENABLED
#  define RTS_MUTEX(MUTEX)                                                                                                     \
    do {        /* standard CPP macro protection */                                                                            \
        RTS_mutex_t *RTS_Mp_mutex = &(MUTEX); /* saved for when we need to unlock it */                                        \
        int RTS_Mp_err = RTS_mutex_lock(RTS_Mp_mutex);                                                                         \
        assert(0==RTS_Mp_err);                                                                                                 \
        do {    /* so we can catch "break" statements */                                                                       \
            try {

#  define RTS_MUTEX_END                                                                                                        \
            } catch (...) {                                                                                                    \
                RTS_Mp_err = RTS_mutex_unlock(RTS_Mp_mutex);                                                                   \
                assert(0==RTS_Mp_err);                                                                                         \
                throw;                                                                                                         \
            }                                                                                                                  \
        } while (0);                                                                                                           \
        RTS_Mp_err = RTS_mutex_unlock(RTS_Mp_mutex);                                                                           \
        assert(0==RTS_Mp_err);                                                                                                 \
    } while (0)
#else
#  define RTS_MUTEX(MUTEX)                                                                                                     \
    do {
#  define RTS_MUTEX_END                                                                                                        \
    } while (0)
#endif

/******************************************************************************************************************************
 *                                      Types and functions for mutexes
 ******************************************************************************************************************************/

#define RTS_MUTEX_MAGIC 0x1a95a713

#ifdef ROSE_THREADS_ENABLED

struct RTS_mutex_t {
    unsigned magic;
    RTS_Layer layer;
    pthread_mutex_t mutex;
};

#define RTS_MUTEX_INITIALIZER(LAYER) { RTS_MUTEX_MAGIC, (LAYER), PTHREAD_MUTEX_INITIALIZER }

int RTS_mutex_init(RTS_mutex_t*, RTS_Layer, pthread_mutexattr_t*);

#else

struct RTS_mutex_t {
    int dummy;
};

#define RTS_MUTEX_INITIALIZER(LAYER) { 0 }

int RTS_mutex_init(RTS_mutex_t*, RTS_Layer, void*);

#endif

int RTS_mutex_lock(RTS_mutex_t*);

int RTS_mutex_unlock(RTS_mutex_t*);




/*******************************************************************************************************************************
 *                                      Paired macros for using RTS_rwlock_t
 *******************************************************************************************************************************/

#ifdef ROSE_THREADS_ENABLED
#  define RTS_RWLOCK(RWLOCK, HOW)                                                                                              \
    do {        /* standard CPP macro protection */                                                                            \
        RTS_rwlock_t *RTS_Wp_rwlock = &(RWLOCK); /* saved for when we need to unlock it */                                     \
        int RTS_Wp_err = RTS_rwlock_##HOW(RTS_Wp_rwlock);                                                                      \
        assert(0==RTS_Wp_err);                                                                                                 \
        do {    /* so we can catch "break" statements */                                                                       \
            try {
                
#  define RTS_RWLOCK_END                                                                                                       \
            } catch (...) {                                                                                                    \
                RTS_Wp_err = RTS_rwlock_unlock(RTS_Wp_rwlock);                                                                 \
                assert(0==RTS_Wp_err);                                                                                         \
                throw;                                                                                                         \
            }                                                                                                                  \
        } while (0);                                                                                                           \
        RTS_Wp_err = RTS_rwlock_unlock(RTS_Wp_rwlock);                                                                         \
        assert(0==RTS_Wp_err);                                                                                                 \
    } while (0)

#else
#  define RTS_RWLOCK(RWLOCK, HOW)                                                                                              \
    do {
#  define RTS_RWLOCK_END                                                                                                       \
    } while (0)
#endif

#define RTS_READ(RWLOCK)        RTS_RWLOCK(RWLOCK, rdlock)                      
#define RTS_READ_END            RTS_RWLOCK_END                                  
#define RTS_WRITE(RWLOCK)       RTS_RWLOCK(RWLOCK, wrlock)                      
#define RTS_WRITE_END           RTS_RWLOCK_END                                  
/*******************************************************************************************************************************
 *                                      Types and functions for RTS_rwlock_t
 *
 * Programmers should generally use the RTS_READ and RTS_WRITE macros in their source code. The symbols defined here are
 * similar to pthread_rwlock* symbols and are mostly to support RTS_READ and RTS_WRITE macros (like how the RTS_mutex*
 * symbols support the RTS_MUTEX macro).
 *******************************************************************************************************************************/

#ifdef ROSE_THREADS_ENABLED
struct RTS_rwlock_t {
    unsigned magic;                             /* always RTS_RWLOCK_MAGIC after initialization */
    RTS_Layer layer;                            /* software layer to which this lock belongs, or zero */
    pthread_rwlock_t rwlock;                    /* the main read-write lock */
    RTS_mutex_t mutex;                          /* mutex to protect the following data members */
    size_t nlocks;                              /* number of write locks held */
    pthread_t owner;                            /* thread that currently holds the write lock */
};
#else
struct RTS_rwlock_t {
    int dummy;
};
#endif

#define RTS_RWLOCK_MAGIC 0x20e7f3f4

#ifdef ROSE_THREADS_ENABLED
#  define RTS_RWLOCK_INITIALIZER(LAYER) { RTS_RWLOCK_MAGIC,                                                                    \
                                          (LAYER),                                                                             \
                                          PTHREAD_RWLOCK_INITIALIZER,                                                          \
                                          RTS_MUTEX_INITIALIZER(RTS_LAYER_DONTCARE),                                           \
                                          0/*...*/                                                                             \
                                         }
#else
#  define RTS_RWLOCK_INITIALIZER(LAYER) { 0 }
#endif

#ifdef ROSE_THREADS_ENABLED

int RTS_rwlock_init(RTS_rwlock_t *rwlock, RTS_Layer, pthread_rwlockattr_t *wrlock_attrs);
#else
int RTS_rwlock_init(RTS_rwlock_t *rwlock, RTS_Layer, void                 *wrlock_attrs);
#endif
              
int RTS_rwlock_rdlock(RTS_rwlock_t *rwlock);

int RTS_rwlock_wrlock(RTS_rwlock_t *rwlock);

int RTS_rwlock_unlock(RTS_rwlock_t *rwlock);



/*******************************************************************************************************************************
 *                                      Paired macros for initialization functions
 *******************************************************************************************************************************/


#ifdef ROSE_THREADS_ENABLED
#  define RTS_INIT(MUTEX, ALLOW_RECURSION)                                                                                     \
    do {                                                                                                                       \
        static bool RTS_Is_initialized=false, RTS_Is_initializing=false;        /* "s"==shared; "p"=private */                 \
        static pthread_t RTS_Is_initializer;                                                                                   \
        static pthread_cond_t RTS_Is_condition=PTHREAD_COND_INITIALIZER;                                                       \
        RTS_mutex_t *RTS_Ip_mutex = &(MUTEX);                                                                                  \
        bool RTS_Ip_initialized, RTS_Ip_initializing;                                                                          \
        bool RTS_Ip_allow_recursion = (ALLOW_RECURSION);                                                                       \
                                                                                                                               \
        /* First critical section is only to obtain the initialization status and update it to "initializing" if necessary. We \
         * must release the lock before the RTS_I_LOCK body is executed in case we need to handle recursive calls to the       \
         * RTS_I_LOCK construct. */                                                                                            \
        RTS_MUTEX(MUTEX) {                                                                                                     \
            if (!(RTS_Ip_initialized=RTS_Is_initialized) && !(RTS_Ip_initializing=RTS_Is_initializing)) {                      \
                RTS_Is_initializing = true; /* but leave private copy false so we can detect changed state */                  \
                RTS_Is_initializer = pthread_self();                                                                           \
            }                                                                                                                  \
        } RTS_MUTEX_END;                                                                                                       \
                                                                                                                               \
        if (!RTS_Ip_initialized) {                                                                                             \
            if (!RTS_Ip_initializing) {                                                                                        \
                do { /* so we catch "break" statements in user-supplied code. */                                               \
                    try {


#  define RTS_INIT_END                                                                                                         \
                    } catch (...) {                                                                                            \
                        /* If the user supplied body throws an exception, consider the body to have completed. */              \
                        RTS_MUTEX(*RTS_Ip_mutex) {                                                                             \
                            RTS_Is_initialized = true;                                                                         \
                            RTS_Is_initializing = false;                                                                       \
                            pthread_cond_broadcast(&RTS_Is_condition);                                                         \
                        } RTS_MUTEX_END;                                                                                       \
                        throw;                                                                                                 \
                    }                                                                                                          \
                } while (0);                                                                                                   \
                RTS_MUTEX(*RTS_Ip_mutex) {                                                                                     \
                    RTS_Is_initialized = true;                                                                                 \
                    RTS_Is_initializing = false;                                                                               \
                    pthread_cond_broadcast(&RTS_Is_condition);                                                                 \
                } RTS_MUTEX_END;                                                                                               \
            } else if (pthread_equal(pthread_self(), RTS_Is_initializer)) {                                                    \
                /* This was a recursive call resulting from the user-supplied RTS_I body and we must allow it to continue      \
                 * unimpeded to prevent deadlock. We don't need to be holding the MUTEX lock to access RTS_Is_initializer      \
                 * because it's initialized only the first time through the critical section above--and the only way to reach  \
                 * this point is by this or some other thread having already initialized RTS_Is_initializer. */                \
                if (!RTS_Ip_allow_recursion) {                                                                                 \
                    fprintf(stderr, "RTS_I_LOCK body made a recursive call. Aborting...\n");                                   \
                    abort();                                                                                                   \
                }                                                                                                              \
            } else {                                                                                                           \
                /* This is some other thread which is not in charge of initializing the class, bug which arrived to the        \
                 * RTS_I_LOCK before the first thread completed the initialization. */                                         \
                RTS_MUTEX(*RTS_Ip_mutex) {                                                                                     \
                    while (!RTS_Is_initialized)                                                                                \
                        pthread_cond_wait(&RTS_Is_condition, &(RTS_Ip_mutex->mutex));                                          \
                } RTS_MUTEX_END;                                                                                               \
            }                                                                                                                  \
        }                                                                                                                      \
    } while (0)
#else
#  define RTS_INIT(MUTEX, ALLOW_RECURSION)                                                                                     \
    do {                                                                                                                       \
        static bool RTS_Is_initialized=false;                                                                                  \
        if (!RTS_Is_initialized) {                                                                                             \
            RTS_Is_initialized = true;                                                                                         \
            do {
#  define RTS_INIT_END                                                                                                         \
            } while (0);                                                                                                       \
        }                                                                                                                      \
    } while (0)
#endif

#define RTS_INIT_RECURSIVE(MUTEX)       RTS_INIT(MUTEX, true)                   
#define RTS_INIT_NONRECURSIVE(MUTEX)    RTS_INIT(MUTEX, false)                  
/******************************************************************************************************************************
 *                                      Support for messages
 ******************************************************************************************************************************/

class RTS_Message {
public:
    class Prefix {
    public:
        virtual ~Prefix() {};
        virtual void operator()(FILE*) {}
    };

    RTS_Message(FILE *f, Prefix *p)
        : f(f), p(p), buffer(NULL), bufsz(0), interrupted(false) {
        ctor();
    }

    ~RTS_Message() {
        dtor();
    }

    void set_file(FILE *f) {
        this->f = f;
    }

    FILE *get_file() const {
        return f;
    }

    RTS_Message& multipart(const std::string &name, const char *fmt, ...) __attribute__((format(printf, 3, 4)));

    RTS_Message& more(const char *fmt, ...) __attribute__((format(printf, 2, 3)));

    void multipart_end();

    RTS_Message& mesg(const char *fmt, ...) __attribute__((format(printf, 2, 3)));

    RTS_Message& brief(const char *fmt, ...) __attribute__((format(printf, 2, 3)));

    void brief_begin(const char *fmt, ...) __attribute__((format(printf, 2, 3)));

    void brief_end(const char *fmt, ...) __attribute__((format(printf, 2, 3)));

    int lock();

    int unlock(bool sol=true);

private:
    RTS_Message() {abort();}
    RTS_Message& operator=(RTS_Message&) { abort(); return *this; } // return is to silence Klocwork
    void ctor();                                        
    void dtor();                                        
    void terminate();                                   
    void prefix();                                      
    void output_lines(const char *s);                   
    void format(const char *fmt, va_list, va_list);    
    static RTS_rwlock_t rwlock;                         
    static RTS_Message *in_multi;                       
    static bool sol;                                    
    FILE *f;                                            
    Prefix *p;                                          
    char *buffer;                                       
    size_t bufsz;                                       
    std::string name;                                   
    bool interrupted;                                   
};

/******************************************************************************************************************************
 *                                      Paired macros for messages
 ******************************************************************************************************************************/

#ifdef ROSE_THREADS_ENABLED
#  define RTS_MESSAGE(MESG)                                                                                                    \
    do {                                                                                                                       \
        RTS_Message *RTS_Mp_mesg = &(MESG);                                                                                    \
        int RTS_Mp_err = RTS_Mp_mesg->lock();                                                                                  \
        assert(0==RTS_Mp_err);                                                                                                 \
        do {                                                                                                                   \
            try {

#  define RTS_MESSAGE_END(SOL)                                                                                                 \
            } catch (...) {                                                                                                    \
                RTS_Mp_err = RTS_Mp_mesg->unlock((SOL));                                                                       \
                assert(0==RTS_Mp_err);                                                                                         \
                throw;                                                                                                         \
            }                                                                                                                  \
        } while (0);                                                                                                           \
        RTS_Mp_err = RTS_Mp_mesg->unlock((SOL));                                                                               \
        assert(0==RTS_Mp_err);                                                                                                 \
    } while (0)
#else
#  define RTS_MESSAGE(MESG)                                                                                                    \
    do {
#  define RTS_MESSAGE_END(SOL)                                                                                                 \
    } while (0)
#endif

#endif /* !ROSE_threadSupport_H !*/

---