internals.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533
  1. /* Linuxthreads - a simple clone()-based implementation of Posix */
  2. /* threads for Linux. */
  3. /* Copyright (C) 1996 Xavier Leroy (Xavier.Leroy@inria.fr) */
  4. /* */
  5. /* This program is free software; you can redistribute it and/or */
  6. /* modify it under the terms of the GNU Library General Public License */
  7. /* as published by the Free Software Foundation; either version 2 */
  8. /* of the License, or (at your option) any later version. */
  9. /* */
  10. /* This program is distributed in the hope that it will be useful, */
  11. /* but WITHOUT ANY WARRANTY; without even the implied warranty of */
  12. /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */
  13. /* GNU Library General Public License for more details. */
  14. #ifndef _INTERNALS_H
  15. #define _INTERNALS_H 1
  16. /* Internal data structures */
  17. /* Includes */
  18. #include <bits/libc-tsd.h> /* for _LIBC_TSD_KEY_N */
  19. #include <limits.h>
  20. #include <setjmp.h>
  21. #include <signal.h>
  22. #include <unistd.h>
  23. #include <bits/stackinfo.h>
  24. #include <sys/types.h>
  25. #include <sys/wait.h>
  26. #include "pt-machine.h"
  27. #include "semaphore.h"
  28. #include "../linuxthreads.old_db/thread_dbP.h"
  29. #ifdef __UCLIBC_HAS_XLOCALE__
  30. #include <bits/uClibc_locale.h>
  31. #endif /* __UCLIBC_HAS_XLOCALE__ */
  32. /* Use a funky version in a probably vein attempt at preventing gdb
  33. * from dlopen()'ing glibc's libthread_db library... */
  34. #define VERSION __stringify(__UCLIBC_MAJOR__) "." __stringify(__UCLIBC_MINOR__) "." __stringify(__UCLIBC_SUBLEVEL__)
  35. #ifndef THREAD_GETMEM
  36. # define THREAD_GETMEM(descr, member) descr->member
  37. #endif
  38. #ifndef THREAD_GETMEM_NC
  39. # define THREAD_GETMEM_NC(descr, member) descr->member
  40. #endif
  41. #ifndef THREAD_SETMEM
  42. # define THREAD_SETMEM(descr, member, value) descr->member = (value)
  43. #endif
  44. #ifndef THREAD_SETMEM_NC
  45. # define THREAD_SETMEM_NC(descr, member, value) descr->member = (value)
  46. #endif
  47. /* Arguments passed to thread creation routine */
  48. struct pthread_start_args {
  49. void * (*start_routine)(void *); /* function to run */
  50. void * arg; /* its argument */
  51. sigset_t mask; /* initial signal mask for thread */
  52. int schedpolicy; /* initial scheduling policy (if any) */
  53. struct sched_param schedparam; /* initial scheduling parameters (if any) */
  54. };
  55. /* We keep thread specific data in a special data structure, a two-level
  56. array. The top-level array contains pointers to dynamically allocated
  57. arrays of a certain number of data pointers. So we can implement a
  58. sparse array. Each dynamic second-level array has
  59. PTHREAD_KEY_2NDLEVEL_SIZE
  60. entries. This value shouldn't be too large. */
  61. #define PTHREAD_KEY_2NDLEVEL_SIZE 32
  62. /* We need to address PTHREAD_KEYS_MAX key with PTHREAD_KEY_2NDLEVEL_SIZE
  63. keys in each subarray. */
  64. #define PTHREAD_KEY_1STLEVEL_SIZE \
  65. ((PTHREAD_KEYS_MAX + PTHREAD_KEY_2NDLEVEL_SIZE - 1) \
  66. / PTHREAD_KEY_2NDLEVEL_SIZE)
  67. typedef void (*destr_function)(void *);
  68. struct pthread_key_struct {
  69. int in_use; /* already allocated? */
  70. destr_function destr; /* destruction routine */
  71. };
  72. #define PTHREAD_START_ARGS_INITIALIZER { NULL, NULL, {{0, }}, 0, { 0 } }
  73. /* The type of thread descriptors */
  74. typedef struct _pthread_descr_struct * pthread_descr;
  75. /* Callback interface for removing the thread from waiting on an
  76. object if it is cancelled while waiting or about to wait.
  77. This hold a pointer to the object, and a pointer to a function
  78. which ``extricates'' the thread from its enqueued state.
  79. The function takes two arguments: pointer to the wait object,
  80. and a pointer to the thread. It returns 1 if an extrication
  81. actually occured, and hence the thread must also be signalled.
  82. It returns 0 if the thread had already been extricated. */
  83. typedef struct _pthread_extricate_struct {
  84. void *pu_object;
  85. int (*pu_extricate_func)(void *, pthread_descr);
  86. } pthread_extricate_if;
  87. /* Atomic counter made possible by compare_and_swap */
  88. struct pthread_atomic {
  89. long p_count;
  90. int p_spinlock;
  91. };
  92. /* Context info for read write locks. The pthread_rwlock_info structure
  93. is information about a lock that has been read-locked by the thread
  94. in whose list this structure appears. The pthread_rwlock_context
  95. is embedded in the thread context and contains a pointer to the
  96. head of the list of lock info structures, as well as a count of
  97. read locks that are untracked, because no info structure could be
  98. allocated for them. */
  99. struct _pthread_rwlock_t;
  100. typedef struct _pthread_rwlock_info {
  101. struct _pthread_rwlock_info *pr_next;
  102. struct _pthread_rwlock_t *pr_lock;
  103. int pr_lock_count;
  104. } pthread_readlock_info;
  105. struct _pthread_descr_struct {
  106. pthread_descr p_nextlive, p_prevlive;
  107. /* Double chaining of active threads */
  108. pthread_descr p_nextwaiting; /* Next element in the queue holding the thr */
  109. pthread_descr p_nextlock; /* can be on a queue and waiting on a lock */
  110. pthread_t p_tid; /* Thread identifier */
  111. int p_pid; /* PID of Unix process */
  112. int p_priority; /* Thread priority (== 0 if not realtime) */
  113. struct _pthread_fastlock * p_lock; /* Spinlock for synchronized accesses */
  114. int p_signal; /* last signal received */
  115. sigjmp_buf * p_signal_jmp; /* where to siglongjmp on a signal or NULL */
  116. sigjmp_buf * p_cancel_jmp; /* where to siglongjmp on a cancel or NULL */
  117. char p_terminated; /* true if terminated e.g. by pthread_exit */
  118. char p_detached; /* true if detached */
  119. char p_exited; /* true if the assoc. process terminated */
  120. void * p_retval; /* placeholder for return value */
  121. int p_retcode; /* placeholder for return code */
  122. pthread_descr p_joining; /* thread joining on that thread or NULL */
  123. struct _pthread_cleanup_buffer * p_cleanup; /* cleanup functions */
  124. char p_cancelstate; /* cancellation state */
  125. char p_canceltype; /* cancellation type (deferred/async) */
  126. char p_canceled; /* cancellation request pending */
  127. int * p_errnop; /* pointer to used errno variable */
  128. int p_errno; /* error returned by last system call */
  129. int * p_h_errnop; /* pointer to used h_errno variable */
  130. int p_h_errno; /* error returned by last netdb function */
  131. char * p_in_sighandler; /* stack address of sighandler, or NULL */
  132. char p_sigwaiting; /* true if a sigwait() is in progress */
  133. struct pthread_start_args p_start_args; /* arguments for thread creation */
  134. void ** p_specific[PTHREAD_KEY_1STLEVEL_SIZE]; /* thread-specific data */
  135. void * p_libc_specific[_LIBC_TSD_KEY_N]; /* thread-specific data for libc */
  136. int p_userstack; /* nonzero if the user provided the stack */
  137. void *p_guardaddr; /* address of guard area or NULL */
  138. size_t p_guardsize; /* size of guard area */
  139. pthread_descr p_self; /* Pointer to this structure */
  140. int p_nr; /* Index of descriptor in __pthread_handles */
  141. int p_report_events; /* Nonzero if events must be reported. */
  142. td_eventbuf_t p_eventbuf; /* Data for event. */
  143. struct pthread_atomic p_resume_count; /* number of times restart() was
  144. called on thread */
  145. char p_woken_by_cancel; /* cancellation performed wakeup */
  146. char p_condvar_avail; /* flag if conditional variable became avail */
  147. char p_sem_avail; /* flag if semaphore became available */
  148. pthread_extricate_if *p_extricate; /* See above */
  149. pthread_readlock_info *p_readlock_list; /* List of readlock info structs */
  150. pthread_readlock_info *p_readlock_free; /* Free list of structs */
  151. int p_untracked_readlock_count; /* Readlocks not tracked by list */
  152. /* New elements must be added at the end. */
  153. #ifdef __UCLIBC_HAS_XLOCALE__
  154. __locale_t locale; /* thread-specific locale from uselocale() only! */
  155. #endif /* __UCLIBC_HAS_XLOCALE__ */
  156. } __attribute__ ((aligned(32))); /* We need to align the structure so that
  157. doubles are aligned properly. This is 8
  158. bytes on MIPS and 16 bytes on MIPS64.
  159. 32 bytes might give better cache
  160. utilization. */
  161. /* The type of thread handles. */
  162. typedef struct pthread_handle_struct * pthread_handle;
  163. struct pthread_handle_struct {
  164. struct _pthread_fastlock h_lock; /* Fast lock for sychronized access */
  165. pthread_descr h_descr; /* Thread descriptor or NULL if invalid */
  166. char * h_bottom; /* Lowest address in the stack thread */
  167. };
  168. /* The type of messages sent to the thread manager thread */
  169. struct pthread_request {
  170. pthread_descr req_thread; /* Thread doing the request */
  171. enum { /* Request kind */
  172. REQ_CREATE, REQ_FREE, REQ_PROCESS_EXIT, REQ_MAIN_THREAD_EXIT,
  173. REQ_POST, REQ_DEBUG, REQ_KICK
  174. } req_kind;
  175. union { /* Arguments for request */
  176. struct { /* For REQ_CREATE: */
  177. const pthread_attr_t * attr; /* thread attributes */
  178. void * (*fn)(void *); /* start function */
  179. void * arg; /* argument to start function */
  180. sigset_t mask; /* signal mask */
  181. } create;
  182. struct { /* For REQ_FREE: */
  183. pthread_t thread_id; /* identifier of thread to free */
  184. } free;
  185. struct { /* For REQ_PROCESS_EXIT: */
  186. int code; /* exit status */
  187. } exit;
  188. void * post; /* For REQ_POST: the semaphore */
  189. } req_args;
  190. };
  191. /* Signals used for suspend/restart and for cancellation notification. */
  192. extern int __pthread_sig_restart;
  193. extern int __pthread_sig_cancel;
  194. /* Signal used for interfacing with gdb */
  195. extern int __pthread_sig_debug;
  196. /* Global array of thread handles, used for validating a thread id
  197. and retrieving the corresponding thread descriptor. Also used for
  198. mapping the available stack segments. */
  199. extern struct pthread_handle_struct __pthread_handles[PTHREAD_THREADS_MAX];
  200. /* Descriptor of the initial thread */
  201. extern struct _pthread_descr_struct __pthread_initial_thread;
  202. /* Descriptor of the manager thread */
  203. extern struct _pthread_descr_struct __pthread_manager_thread;
  204. /* Descriptor of the main thread */
  205. extern pthread_descr __pthread_main_thread;
  206. /* Limit between the stack of the initial thread (above) and the
  207. stacks of other threads (below). Aligned on a STACK_SIZE boundary.
  208. Initially 0, meaning that the current thread is (by definition)
  209. the initial thread. */
  210. extern char *__pthread_initial_thread_bos;
  211. #ifndef __ARCH_USE_MMU__
  212. /* For non-MMU systems, we have no idea the bounds of the initial thread
  213. * stack, so we have to track it on the fly relative to other stacks. Do
  214. * so by scaling back our assumptions on the limits of the bos/tos relative
  215. * to the known mid point. See also the comments in pthread_initialize(). */
  216. extern char *__pthread_initial_thread_tos, *__pthread_initial_thread_mid;
  217. #define NOMMU_INITIAL_THREAD_BOUNDS(tos,bos) \
  218. do { \
  219. char *__tos = (tos); \
  220. char *__bos = (bos); \
  221. if (__tos >= __pthread_initial_thread_bos && \
  222. __bos < __pthread_initial_thread_tos) { \
  223. if (__bos < __pthread_initial_thread_mid) \
  224. __pthread_initial_thread_bos = __tos; \
  225. else \
  226. __pthread_initial_thread_tos = __bos; \
  227. } \
  228. } while (0)
  229. #else
  230. #define NOMMU_INITIAL_THREAD_BOUNDS(tos,bos) /* empty */
  231. #endif /* __ARCH_USE_MMU__ */
  232. /* Indicate whether at least one thread has a user-defined stack (if 1),
  233. or all threads have stacks supplied by LinuxThreads (if 0). */
  234. extern int __pthread_nonstandard_stacks;
  235. /* File descriptor for sending requests to the thread manager.
  236. Initially -1, meaning that __pthread_initialize_manager must be called. */
  237. extern int __pthread_manager_request;
  238. /* Other end of the pipe for sending requests to the thread manager. */
  239. extern int __pthread_manager_reader;
  240. /* Limits of the thread manager stack. */
  241. extern char *__pthread_manager_thread_bos;
  242. extern char *__pthread_manager_thread_tos;
  243. /* Pending request for a process-wide exit */
  244. extern int __pthread_exit_requested, __pthread_exit_code;
  245. /* Set to 1 by gdb if we're debugging */
  246. extern volatile int __pthread_threads_debug;
  247. /* Globally enabled events. */
  248. extern volatile td_thr_events_t __pthread_threads_events;
  249. /* Pointer to descriptor of thread with last event. */
  250. extern volatile pthread_descr __pthread_last_event;
  251. /* Return the handle corresponding to a thread id */
  252. static __inline__ pthread_handle thread_handle(pthread_t id)
  253. {
  254. return &__pthread_handles[id % PTHREAD_THREADS_MAX];
  255. }
  256. /* Validate a thread handle. Must have acquired h->h_spinlock before. */
  257. static __inline__ int invalid_handle(pthread_handle h, pthread_t id)
  258. {
  259. return h->h_descr == NULL || h->h_descr->p_tid != id;
  260. }
  261. /* Fill in defaults left unspecified by pt-machine.h. */
  262. /* The page size we can get from the system. This should likely not be
  263. changed by the machine file but, you never know. */
  264. extern size_t __pagesize;
  265. #include <bits/uClibc_page.h>
  266. #ifndef PAGE_SIZE
  267. #define PAGE_SIZE (sysconf (_SC_PAGESIZE))
  268. #endif
  269. /* The max size of the thread stack segments. If the default
  270. THREAD_SELF implementation is used, this must be a power of two and
  271. a multiple of PAGE_SIZE. */
  272. #ifndef STACK_SIZE
  273. #ifdef __ARCH_USE_MMU__
  274. #define STACK_SIZE (2 * 1024 * 1024)
  275. #else
  276. #define STACK_SIZE (4 * __pagesize)
  277. #endif
  278. #endif
  279. /* The initial size of the thread stack. Must be a multiple of PAGE_SIZE. */
  280. #ifndef INITIAL_STACK_SIZE
  281. #define INITIAL_STACK_SIZE (4 * __pagesize)
  282. #endif
  283. /* Size of the thread manager stack. The "- 32" avoids wasting space
  284. with some malloc() implementations. */
  285. #ifndef THREAD_MANAGER_STACK_SIZE
  286. #define THREAD_MANAGER_STACK_SIZE (2 * __pagesize - 32)
  287. #endif
  288. /* The base of the "array" of thread stacks. The array will grow down from
  289. here. Defaults to the calculated bottom of the initial application
  290. stack. */
  291. #ifndef THREAD_STACK_START_ADDRESS
  292. #define THREAD_STACK_START_ADDRESS __pthread_initial_thread_bos
  293. #endif
  294. /* Get some notion of the current stack. Need not be exactly the top
  295. of the stack, just something somewhere in the current frame. */
  296. #ifndef CURRENT_STACK_FRAME
  297. #define CURRENT_STACK_FRAME ({ char __csf; &__csf; })
  298. #endif
  299. /* If MEMORY_BARRIER isn't defined in pt-machine.h, assume the
  300. architecture doesn't need a memory barrier instruction (e.g. Intel
  301. x86). Still we need the compiler to respect the barrier and emit
  302. all outstanding operations which modify memory. Some architectures
  303. distinguish between full, read and write barriers. */
  304. #ifndef MEMORY_BARRIER
  305. #define MEMORY_BARRIER() __asm__ ("" : : : "memory")
  306. #endif
  307. #ifndef READ_MEMORY_BARRIER
  308. #define READ_MEMORY_BARRIER() MEMORY_BARRIER()
  309. #endif
  310. #ifndef WRITE_MEMORY_BARRIER
  311. #define WRITE_MEMORY_BARRIER() MEMORY_BARRIER()
  312. #endif
  313. /* Recover thread descriptor for the current thread */
  314. extern pthread_descr __pthread_find_self (void) __attribute__ ((const));
  315. static __inline__ pthread_descr thread_self (void) __attribute__ ((const));
  316. static __inline__ pthread_descr thread_self (void)
  317. {
  318. #ifdef THREAD_SELF
  319. return THREAD_SELF;
  320. #else
  321. char *sp = CURRENT_STACK_FRAME;
  322. #ifdef __ARCH_USE_MMU__
  323. if (sp >= __pthread_initial_thread_bos)
  324. return &__pthread_initial_thread;
  325. else if (sp >= __pthread_manager_thread_bos
  326. && sp < __pthread_manager_thread_tos)
  327. return &__pthread_manager_thread;
  328. else if (__pthread_nonstandard_stacks)
  329. return __pthread_find_self();
  330. else
  331. return (pthread_descr)(((unsigned long)sp | (STACK_SIZE-1))+1) - 1;
  332. #else
  333. /* For non-MMU we need to be more careful about the initial thread stack.
  334. * We refine the initial thread stack bounds dynamically as we allocate
  335. * the other stack frame such that it doesn't overlap with them. Then
  336. * we can be sure to pick the right thread according to the current SP */
  337. /* Since we allow other stack frames to be above or below, we need to
  338. * treat this case special. When pthread_initialize() wasn't called yet,
  339. * only the initial thread is there. */
  340. if (__pthread_initial_thread_bos == NULL) {
  341. return &__pthread_initial_thread;
  342. }
  343. else if (sp >= __pthread_initial_thread_bos
  344. && sp < __pthread_initial_thread_tos) {
  345. return &__pthread_initial_thread;
  346. }
  347. else if (sp >= __pthread_manager_thread_bos
  348. && sp < __pthread_manager_thread_tos) {
  349. return &__pthread_manager_thread;
  350. }
  351. else {
  352. return __pthread_find_self();
  353. }
  354. #endif /* __ARCH_USE_MMU__ */
  355. #endif
  356. }
  357. /* Max number of times we must spin on a spinlock calling sched_yield().
  358. After MAX_SPIN_COUNT iterations, we put the calling thread to sleep. */
  359. #ifndef MAX_SPIN_COUNT
  360. #define MAX_SPIN_COUNT 50
  361. #endif
  362. /* Duration of sleep (in nanoseconds) when we can't acquire a spinlock
  363. after MAX_SPIN_COUNT iterations of sched_yield().
  364. With the 2.0 and 2.1 kernels, this MUST BE > 2ms.
  365. (Otherwise the kernel does busy-waiting for realtime threads,
  366. giving other threads no chance to run.) */
  367. #ifndef SPIN_SLEEP_DURATION
  368. #define SPIN_SLEEP_DURATION 2000001
  369. #endif
  370. /* Defined and used in libc.so. */
  371. extern int __libc_multiple_threads attribute_hidden;
  372. extern int __librt_multiple_threads;
  373. /* Internal global functions */
  374. void __pthread_do_exit (void *retval, char *currentframe)
  375. __attribute__ ((__noreturn__));
  376. void __pthread_destroy_specifics(void);
  377. void __pthread_perform_cleanup(char *currentframe);
  378. int __pthread_initialize_manager(void);
  379. void __pthread_message(char * fmt, ...)
  380. __attribute__ ((__format__ (printf, 1, 2)));
  381. int __pthread_manager(void *reqfd);
  382. int __pthread_manager_event(void *reqfd);
  383. void __pthread_manager_sighandler(int sig);
  384. void __pthread_reset_main_thread(void);
  385. void __fresetlockfiles(void);
  386. void __pthread_manager_adjust_prio(int thread_prio);
  387. void __pthread_initialize_minimal (void);
  388. extern void __pthread_exit (void *retval)
  389. #if defined NOT_IN_libc && defined IS_IN_libpthread
  390. attribute_noreturn
  391. #endif
  392. ;
  393. extern int __pthread_attr_setguardsize __P ((pthread_attr_t *__attr,
  394. size_t __guardsize));
  395. extern int __pthread_attr_getguardsize __P ((__const pthread_attr_t *__attr,
  396. size_t *__guardsize));
  397. extern int __pthread_attr_setstackaddr __P ((pthread_attr_t *__attr,
  398. void *__stackaddr));
  399. extern int __pthread_attr_getstackaddr __P ((__const pthread_attr_t *__attr,
  400. void **__stackaddr));
  401. extern int __pthread_attr_setstacksize __P ((pthread_attr_t *__attr,
  402. size_t __stacksize));
  403. extern int __pthread_attr_getstacksize __P ((__const pthread_attr_t *__attr,
  404. size_t *__stacksize));
  405. extern int __pthread_getconcurrency __P ((void));
  406. extern int __pthread_setconcurrency __P ((int __level));
  407. extern void __pthread_kill_other_threads_np __P ((void));
  408. extern void __pthread_restart_old(pthread_descr th);
  409. extern void __pthread_suspend_old(pthread_descr self);
  410. extern int __pthread_timedsuspend_old(pthread_descr self, const struct timespec *abstime);
  411. extern void __pthread_restart_new(pthread_descr th);
  412. extern void __pthread_suspend_new(pthread_descr self);
  413. extern int __pthread_timedsuspend_new(pthread_descr self, const struct timespec *abstime);
  414. extern void __pthread_wait_for_restart_signal(pthread_descr self);
  415. /* Global pointers to old or new suspend functions */
  416. extern void (*__pthread_restart)(pthread_descr);
  417. extern void (*__pthread_suspend)(pthread_descr);
  418. extern __typeof(pthread_mutex_init) __pthread_mutex_init attribute_hidden;
  419. extern __typeof(pthread_mutex_destroy) __pthread_mutex_destroy attribute_hidden;
  420. extern __typeof(pthread_mutex_lock) __pthread_mutex_lock attribute_hidden;
  421. extern __typeof(pthread_mutex_trylock) __pthread_mutex_trylock attribute_hidden;
  422. extern __typeof(pthread_mutex_unlock) __pthread_mutex_attribute_hidden;
  423. /* Prototypes for some of the new semaphore functions. */
  424. extern int __new_sem_post (sem_t * sem);
  425. /* TSD. */
  426. extern int __pthread_internal_tsd_set (int key, const void * pointer);
  427. extern void * __pthread_internal_tsd_get (int key);
  428. extern void ** __attribute__ ((__const__))
  429. __pthread_internal_tsd_address (int key);
  430. /* The functions called the signal events. */
  431. extern void __linuxthreads_create_event (void);
  432. extern void __linuxthreads_death_event (void);
  433. extern void __linuxthreads_reap_event (void);
  434. #include <pthread-functions.h>
  435. extern int * __libc_pthread_init (const struct pthread_functions *functions);
  436. #endif /* internals.h */