Update copyright to LGPL on all files
[dyninst.git] / dyninstAPI_RT / h / dyninstRTExport.h
1 /*
2  * Copyright (c) 1996-2009 Barton P. Miller
3  * 
4  * We provide the Paradyn Parallel Performance Tools (below
5  * described as "Paradyn") on an AS IS basis, and do not warrant its
6  * validity or performance.  We reserve the right to update, modify,
7  * or discontinue this software at any time.  We shall have no
8  * obligation to supply such updates or modifications or any other
9  * form of support to you.
10  * 
11  * By your use of Paradyn, you understand and agree that we (or any
12  * other person or entity with proprietary rights in Paradyn) are
13  * under no obligation to provide either maintenance services,
14  * update services, notices of latent defects, or correction of
15  * defects for Paradyn.
16  * 
17  * This library is free software; you can redistribute it and/or
18  * modify it under the terms of the GNU Lesser General Public
19  * License as published by the Free Software Foundation; either
20  * version 2.1 of the License, or (at your option) any later version.
21  * 
22  * This library is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
25  * Lesser General Public License for more details.
26  * 
27  * You should have received a copy of the GNU Lesser General Public
28  * License along with this library; if not, write to the Free Software
29  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
30  */
31 #ifndef _DYNINST_RT_EXPORT_H_
32 #define _DYNINST_RT_EXPORT_H_
33 #ifndef ASSEMBLER
34   /*  This file contains function prototypes that may be useful for 
35       dyninst users to directly have access to from their own runtime
36       libraries.
37   */
38
39 #if !defined(DLLEXPORT)
40 #if defined (_MSC_VER)
41 /* If we're on Windows, we need to explicetely export these functions: */
42 #define DLLEXPORT __declspec(dllexport) 
43 #else
44 #define DLLEXPORT
45 #endif
46 #endif
47   /*
48     DYNINSTuserMessage(void *msg, unsigned int msg_size) may be used 
49     in conjunction with the dyninstAPI method 
50     BPatch_process::registerUserMessageCallback(), to implement a generic
51     user-defined, asynchronous communications protocol from the mutatee
52     (via this runtime library) to the mutator.
53
54     Calls to DYNINSTuserMessage() will result in <msg> (of <msg_size> bytes)
55     being sent to the mutator, and then passed to the callback function
56     provided by the API user via registerUserMessageCallback().
57
58     Returns zero on success, nonzero on failure.
59   */
60 DLLEXPORT int DYNINSTuserMessage(void *msg, unsigned int msg_size);
61
62 /* Returns the number of threads DYNINST currently knows about.  (Which
63    may differ at certain times from the number of threads actually present.) */
64 DLLEXPORT int DYNINSTthreadCount();
65
66 /**
67  * These function implement a locking mechanism that can be used by 
68  * a user's runtime library.
69  * 
70  * Be sure to always check for DYNINST_LIVE_LOCK and DYNINST_DEAD_LOCK.
71  * When instrumenting multithread or signal-based application as these error
72  * conditions can trigger even on simple synchronization mechanisms.
73  **/
74
75 /* The contents of this structure are subject to change between
76    dyninst versions.  Don't rely on it. */
77 typedef void * dyntid_t;
78 #define DYNINST_INITIAL_LOCK_PID ((void *)-129)
79
80 typedef struct {
81    volatile int mutex;
82    dyntid_t tid;
83 } dyninst_lock_t;
84
85 /* Return values for 'dyninst_lock' */
86 #define DYNINST_LIVE_LOCK      -1
87 #define DYNINST_DEAD_LOCK      -2
88
89 /* Declare a lock already initialized */
90 #define DECLARE_DYNINST_LOCK(lck) dyninst_lock_t lck = {0, DYNINST_INITIAL_LOCK_PID}
91
92 DLLEXPORT void dyninst_init_lock(dyninst_lock_t *lock);
93 DLLEXPORT void dyninst_free_lock(dyninst_lock_t *lock);
94 DLLEXPORT int dyninst_lock(dyninst_lock_t *lock);
95 DLLEXPORT void dyninst_unlock(dyninst_lock_t *lock);
96
97 /**
98  * Functions for retrieving information about threads
99  **/
100 DLLEXPORT unsigned dyninst_maxNumOfThreads();
101 DLLEXPORT unsigned dyninst_threadIndex();
102
103 DLLEXPORT void setNewthrCB(void (*rt_newthr_cb)(int));
104
105 #endif
106 #endif