improve the SB-EXT:GC docstring(s)
[sbcl.git] / src / runtime / runtime.h
1 /*
2  * This software is part of the SBCL system. See the README file for
3  * more information.
4  *
5  * This software is derived from the CMU CL system, which was
6  * written at Carnegie Mellon University and released into the
7  * public domain. The software is in the public domain and is
8  * provided with absolutely no warranty. See the COPYING and CREDITS
9  * files for more information.
10  */
11
12 /* FIXME: Aren't symbols with underscore prefixes supposed to be
13  * reserved for system libraries? Perhaps rename stuff like this
14  * to names like INCLUDED_SBCL_RUNTIME_H. */
15 #ifndef _SBCL_RUNTIME_H_
16 #define _SBCL_RUNTIME_H_
17
18 #if defined(LISP_FEATURE_SB_THREAD)
19 #define thread_self() pthread_self()
20 #define thread_kill pthread_kill
21 #define thread_sigmask pthread_sigmask
22 #define thread_mutex_lock(l) pthread_mutex_lock(l)
23 #define thread_mutex_unlock(l) pthread_mutex_unlock(l)
24 #else
25 #define thread_self() 0
26 #define thread_kill kill_safely
27 #define thread_sigmask sigprocmask
28 #define thread_mutex_lock(l) 0
29 #define thread_mutex_unlock(l) 0
30 #endif
31
32 /* Block blockable interrupts for each SHOW, if not 0. */
33 #define QSHOW_SIGNAL_SAFE 1
34 /* Enable extra-verbose low-level debugging output for signals? (You
35  * probably don't want this unless you're trying to debug very early
36  * cold boot on a new machine, or one where you've just messed up
37  * signal handling.)
38  *
39  * Note: It may be that doing this is fundamentally unsound, since it
40  * causes output from signal handlers, and the i/o libraries aren't
41  * necessarily reentrant. But it can still be very convenient for
42  * figuring out what's going on when you have a signal handling
43  * problem. */
44 #define QSHOW_SIGNALS 0
45 /* Enable low-level debugging output, if not zero. Defaults to enabled
46  * if QSHOW_SIGNALS, disabled otherwise. Change it to 1 if you want
47  * low-level debugging output but not the whole signal mess. */
48 #define QSHOW QSHOW_SIGNALS
49
50 #if QSHOW
51
52 #if QSHOW_SIGNAL_SAFE == 1 && !defined(LISP_FEATURE_WIN32)
53
54 #include <signal.h>
55 extern sigset_t blockable_sigset;
56
57 #define QSHOW_BLOCK                                             \
58         sigset_t oldset;                                        \
59         thread_sigmask(SIG_BLOCK, &blockable_sigset, &oldset);
60 #define QSHOW_UNBLOCK thread_sigmask(SIG_SETMASK,&oldset,0);
61 #else
62 #define QSHOW_BLOCK
63 #define QSHOW_UNBLOCK
64 #endif
65
66 #ifdef LISP_FEATURE_SB_THREAD
67 #define QSHOW_PREFIX fprintf(stderr, "%lu ", pthread_self());
68 #else
69 #define QSHOW_PREFIX
70 #endif
71
72 #define FSHOW(args)                                             \
73     do {                                                        \
74         QSHOW_BLOCK                                             \
75         QSHOW_PREFIX                                            \
76         fprintf args;                                           \
77         QSHOW_UNBLOCK                                           \
78     } while (0)
79 #define SHOW(string) FSHOW((stderr, "/%s\n", string))
80
81 #else
82
83 #define FSHOW(args)
84 #define SHOW(string)
85
86 #endif
87
88 #if QSHOW_SIGNALS
89 #define FSHOW_SIGNAL FSHOW
90 #else
91 #define FSHOW_SIGNAL(args)
92 #endif
93
94 /* KLUDGE: These are in theory machine-dependent and OS-dependent, but
95  * in practice the "foo int" definitions work for all the machines
96  * that SBCL runs on as of 0.6.7. If we port to the Alpha or some
97  * other non-32-bit machine we'll probably need real machine-dependent
98  * and OS-dependent definitions again. */
99 /* even on alpha, int happens to be 4 bytes.  long is longer. */
100 /* FIXME: these names really shouldn't reflect their length and this
101    is not quite right for some of the FFI stuff */
102 typedef unsigned long u64;
103 typedef signed long s64;
104 typedef unsigned int u32;
105 typedef signed int s32;
106
107 /* this is an integral type the same length as a machine pointer */
108 typedef unsigned long pointer_sized_uint_t ;
109
110 #include <sys/types.h>
111
112 #if defined(LISP_FEATURE_SB_THREAD)
113 #include <pthread.h>
114 typedef pthread_t os_thread_t;
115 #else
116 typedef pid_t os_thread_t;
117 #endif
118
119 /* FIXME: we do things this way because of the alpha32 port.  once
120    alpha64 has arrived, all this nastiness can go away */
121 #if 64 == N_WORD_BITS
122 #define LOW_WORD(c) ((pointer_sized_uint_t)c)
123 typedef unsigned long lispobj;
124 #else
125 #define LOW_WORD(c) ((long)(c) & 0xFFFFFFFFL)
126 /* fake it on alpha32 */
127 typedef unsigned int lispobj;
128 #endif
129
130 static inline int
131 lowtag_of(lispobj obj)
132 {
133     return obj & LOWTAG_MASK;
134 }
135
136 static inline int
137 widetag_of(lispobj obj)
138 {
139     return obj & WIDETAG_MASK;
140 }
141
142 static inline unsigned long
143 HeaderValue(lispobj obj)
144 {
145   return obj >> N_WIDETAG_BITS;
146 }
147
148 static inline struct cons *
149 CONS(lispobj obj)
150 {
151   return (struct cons *)(obj - LIST_POINTER_LOWTAG);
152 }
153
154 static inline struct symbol *
155 SYMBOL(lispobj obj)
156 {
157   return (struct symbol *)(obj - OTHER_POINTER_LOWTAG);
158 }
159
160 static inline struct fdefn *
161 FDEFN(lispobj obj)
162 {
163   return (struct fdefn *)(obj - OTHER_POINTER_LOWTAG);
164 }
165
166 /* Is the Lisp object obj something with pointer nature (as opposed to
167  * e.g. a fixnum or character or unbound marker)? */
168 static inline int
169 is_lisp_pointer(lispobj obj)
170 {
171 #if N_WORD_BITS == 64
172     return (obj & 3) == 3;
173 #else
174     return obj & 1;
175 #endif
176 }
177
178 #include "fixnump.h"
179
180 /* Is the Lisp object obj something with immediate nature (e.g. a
181  * fixnum or character or unbound marker)? */
182 static inline int
183 is_lisp_immediate(lispobj obj)
184 {
185     return (fixnump(obj)
186             || (widetag_of(obj) == CHARACTER_WIDETAG)
187 #if N_WORD_BITS == 64
188             || (widetag_of(obj) == SINGLE_FLOAT_WIDETAG)
189 #endif
190             || (widetag_of(obj) == UNBOUND_MARKER_WIDETAG));
191 }
192
193 /* Convert from a lispobj with type bits to a native (ordinary
194  * C/assembly) pointer to the beginning of the object. */
195 static inline lispobj *
196 native_pointer(lispobj obj)
197 {
198     return (lispobj *) ((pointer_sized_uint_t) (obj & ~LOWTAG_MASK));
199 }
200
201 /* inverse operation: create a suitably tagged lispobj from a native
202  * pointer or integer.*/
203 static inline lispobj
204 make_lispobj(void *o, int low_tag)
205 {
206     return LOW_WORD(o) | low_tag;
207 }
208
209 static inline lispobj
210 make_fixnum(long n)
211 {
212     return n << N_FIXNUM_TAG_BITS;
213 }
214
215 static inline long
216 fixnum_value(lispobj n)
217 {
218     return n >> N_FIXNUM_TAG_BITS;
219 }
220
221 #if defined(LISP_FEATURE_WIN32)
222 /* KLUDGE: Avoid double definition of boolean by rpcndr.h included via
223  * shlobj.h.
224  *
225  * FIXME: We should probably arrange to use the rpcndr.h boolean on Windows,
226  * or get rid of our own boolean type.  If the boolean type is only used in
227  * the runtime, and never passed to Lisp, then it doesn't matter which one
228  * we use.
229  */
230 #define boolean rpcndr_boolean
231 #include <shlobj.h>
232 #undef boolean
233 #endif
234 typedef int boolean;
235
236 static inline boolean
237 other_immediate_lowtag_p(lispobj header)
238 {
239     /* These lowtags are spaced 4 apart throughout the lowtag space. */
240     return (lowtag_of(header) & 3) == OTHER_IMMEDIATE_0_LOWTAG;
241 }
242
243 /* KLUDGE: As far as I can tell there's no ANSI C way of saying
244  * "this function never returns". This is the way that you do it
245  * in GCC later than version 2.5 or so. */
246 #if defined(__GNUC__)
247 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 5)
248 #define never_returns __attribute__ ((noreturn))
249 #else
250 #define never_returns
251 #endif
252 #else
253 #define never_returns
254 #endif
255
256 extern void *successful_malloc (size_t size);
257 extern char *copied_string (char *string);
258
259 #endif /* _SBCL_RUNTIME_H_ */