[thirdparty/glibc.git] / htl / pt-internal.h

/* Internal defenitions for pthreads library.
   Copyright (C) 2000-2020 Free Software Foundation, Inc.
   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the GNU C Library;  if not, see
   <https://www.gnu.org/licenses/>.  */

#ifndef _PT_INTERNAL_H
#define _PT_INTERNAL_H	1

#include <pthread.h>
#include <stddef.h>
#include <sched.h>
#include <signal.h>
#include <assert.h>
#include <bits/types/res_state.h>

#include <atomic.h>

#include <pt-key.h>

#include <pt-sysdep.h>
#include <pt-machdep.h>

#if IS_IN (libpthread)
# include <ldsodefs.h>
#endif

#include <tls.h>

/* Thread state.  */
enum pthread_state
{
  /* The thread is running and joinable.  */
  PTHREAD_JOINABLE = 0,
  /* The thread is running and detached.  */
  PTHREAD_DETACHED,
  /* A joinable thread exited and its return code is available.  */
  PTHREAD_EXITED,
  /* The thread structure is unallocated and available for reuse.  */
  PTHREAD_TERMINATED
};

#ifndef PTHREAD_KEY_MEMBERS
# define PTHREAD_KEY_MEMBERS
#endif

#ifndef PTHREAD_SYSDEP_MEMBERS
# define PTHREAD_SYSDEP_MEMBERS
#endif

/* This structure describes a POSIX thread.  */
struct __pthread
{
  /* Thread ID.  */
  pthread_t thread;

  unsigned int nr_refs;		/* Detached threads have a self reference only,
				   while joinable threads have two references.
				   These are used to keep the structure valid at
				   thread destruction.  Detaching/joining a thread
				   drops a reference.  */

  /* Cancellation.  */
  pthread_mutex_t cancel_lock;	/* Protect cancel_xxx members.  */
  void (*cancel_hook) (void *);	/* Called to unblock a thread blocking
				   in a cancellation point (namely,
				   __pthread_cond_timedwait_internal).  */
  void *cancel_hook_arg;
  int cancel_state;
  int cancel_type;
  int cancel_pending;

  /* Thread stack.  */
  void *stackaddr;
  size_t stacksize;
  size_t guardsize;
  int stack;			/* Nonzero if the stack was allocated.  */

  /* Exit status.  */
  void *status;

  /* Thread state.  */
  enum pthread_state state;
  pthread_mutex_t state_lock;	/* Locks the state.  */
  pthread_cond_t state_cond;	/* Signalled when the state changes.  */

  /* Resolver state.  */
  struct __res_state res_state;

  /* Indicates whether is a C11 thread created by thrd_creat.  */
  bool c11;

  /* Initial sigset for the thread.  */
  sigset_t init_sigset;

  /* Thread context.  */
  struct pthread_mcontext mcontext;

  PTHREAD_KEY_MEMBERS

  PTHREAD_SYSDEP_MEMBERS

  tcbhead_t *tcb;

  /* Queue links.  Since PREVP is used to determine if a thread has been
     awaken, it must be protected by the queue lock.  */
  struct __pthread *next, **prevp;
};

/* Enqueue an element THREAD on the queue *HEAD.  */
static inline void
__pthread_enqueue (struct __pthread **head, struct __pthread *thread)
{
  assert (thread->prevp == 0);

  thread->next = *head;
  thread->prevp = head;
  if (*head)
    (*head)->prevp = &thread->next;
  *head = thread;
}

/* Dequeue the element THREAD from the queue it is connected to.  */
static inline void
__pthread_dequeue (struct __pthread *thread)
{
  assert (thread);
  assert (thread->prevp);

  if (thread->next)
    thread->next->prevp = thread->prevp;
  *thread->prevp = thread->next;
  thread->prevp = 0;
}

/* Iterate over QUEUE storing each element in ELEMENT.  */
#define __pthread_queue_iterate(queue, element)				\
  for (struct __pthread *__pdi_next = (queue);				\
       ((element) = __pdi_next)						\
	 && ((__pdi_next = __pdi_next->next),				\
	     1);							\
       )

/* Iterate over QUEUE dequeuing each element, storing it in
   ELEMENT.  */
#define __pthread_dequeuing_iterate(queue, element)			\
  for (struct __pthread *__pdi_next = (queue);				\
       ((element) = __pdi_next)						\
	 && ((__pdi_next = __pdi_next->next),				\
	     ((element)->prevp = 0),					\
	     1);							\
       )

/* The total number of threads currently active.  */
extern unsigned int __pthread_total;

/* The total number of thread IDs currently in use, or on the list of
   available thread IDs.  */
extern int __pthread_num_threads;

/* Concurrency hint.  */
extern int __pthread_concurrency;

/* Array of __pthread structures and its lock.  Indexed by the pthread
   id minus one.  (Why not just use the pthread id?  Because some
   brain-dead users of the pthread interface incorrectly assume that 0
   is an invalid pthread id.)  */
extern struct __pthread **__pthread_threads;
extern int __pthread_max_threads;
extern pthread_rwlock_t __pthread_threads_lock;

#define __pthread_getid(thread) \
  ({ struct __pthread *__t = NULL;                                           \
     __pthread_rwlock_rdlock (&__pthread_threads_lock);                      \
     if (thread <= __pthread_max_threads)                                    \
       __t = __pthread_threads[thread - 1];                                  \
     __pthread_rwlock_unlock (&__pthread_threads_lock);                      \
     __t; })

#define __pthread_setid(thread, pthread) \
  __pthread_rwlock_wrlock (&__pthread_threads_lock);                         \
  __pthread_threads[thread - 1] = pthread;                                   \
  __pthread_rwlock_unlock (&__pthread_threads_lock);

/* Similar to pthread_self, but returns the thread descriptor instead
   of the thread ID.  */
#ifndef _pthread_self
extern struct __pthread *_pthread_self (void);
#endif

/* Stores the stack of cleanup handlers for the thread.  */
extern __thread struct __pthread_cancelation_handler *__pthread_cleanup_stack;
\f

/* Initialize the pthreads library.  */
extern void ___pthread_init (void);

/* Internal version of pthread_create.  Rather than return the new
   tid, we return the whole __pthread structure in *PTHREAD.  */
extern int __pthread_create_internal (struct __pthread **__restrict pthread,
				      const pthread_attr_t *__restrict attr,
				      void *(*start_routine) (void *),
				      void *__restrict arg);

/* Allocate a new thread structure and a pthread thread ID (but not a
   kernel thread or a stack).  THREAD has one reference.  */
extern int __pthread_alloc (struct __pthread **thread);

/* Deallocate the thread structure.  This is the dual of
   __pthread_alloc (N.B. it does not call __pthread_stack_dealloc nor
   __pthread_thread_terminate).  THREAD loses one reference and is
   released if the reference counter drops to 0.  */
extern void __pthread_dealloc (struct __pthread *thread);


/* Allocate a stack of size STACKSIZE.  The stack base shall be
   returned in *STACKADDR.  */
extern int __pthread_stack_alloc (void **stackaddr, size_t stacksize);

/* Deallocate the stack STACKADDR of size STACKSIZE.  */
extern void __pthread_stack_dealloc (void *stackaddr, size_t stacksize);


/* Setup thread THREAD's context.  */
extern int __pthread_setup (struct __pthread *__restrict thread,
			    void (*entry_point) (struct __pthread *,
						 void *(*)(void *),
						 void *),
			    void *(*start_routine) (void *),
			    void *__restrict arg);


/* Allocate a kernel thread (and any miscellaneous system dependent
   resources) for THREAD; it must not be placed on the run queue.  */
extern int __pthread_thread_alloc (struct __pthread *thread);

/* Start THREAD making it eligible to run.  */
extern int __pthread_thread_start (struct __pthread *thread);

/* Terminate the kernel thread associated with THREAD, and deallocate its
   stack as well as any other kernel resource associated with it.
   In addition, THREAD looses one reference.

   This function can be called by any thread, including the target thread.
   Since some resources that are destroyed along the kernel thread are
   stored in thread-local variables, the conditions required for this
   function to behave correctly are a bit unusual : as long as the target
   thread hasn't been started, any thread can terminate it, but once it
   has started, no other thread can terminate it, so that thread-local
   variables created by that thread are correctly released.  */
extern void __pthread_thread_terminate (struct __pthread *thread);


/* Called by a thread just before it calls the provided start
   routine.  */
extern void __pthread_startup (void);

/* Block THREAD.  */
extern void __pthread_block (struct __pthread *thread);

/* Block THREAD until *ABSTIME is reached.  */
extern error_t __pthread_timedblock (struct __pthread *__restrict thread,
				     const struct timespec *__restrict abstime,
				     clockid_t clock_id);

/* Block THREAD with interrupts.  */
extern error_t __pthread_block_intr (struct __pthread *thread);

/* Block THREAD until *ABSTIME is reached, with interrupts.  */
extern error_t __pthread_timedblock_intr (struct __pthread *__restrict thread,
					  const struct timespec *__restrict abstime,
					  clockid_t clock_id);

/* Wakeup THREAD.  */
extern void __pthread_wakeup (struct __pthread *thread);


/* Perform a cancelation.  The CANCEL_LOCK member of the given thread must
   be locked before calling this function, which must unlock it.  */
extern int __pthread_do_cancel (struct __pthread *thread);


/* Initialize the thread specific data structures.  THREAD must be the
   calling thread.  */
extern error_t __pthread_init_specific (struct __pthread *thread);

/* Call the destructors on all of the thread specific data in THREAD.
   THREAD must be the calling thread.  */
extern void __pthread_destroy_specific (struct __pthread *thread);


/* Initialize newly create thread *THREAD's signal state data
   structures.  */
extern error_t __pthread_sigstate_init (struct __pthread *thread);

/* Destroy the signal state data structures associcated with thread
   *THREAD.  */
extern void __pthread_sigstate_destroy (struct __pthread *thread);

/* Modify thread *THREAD's signal state.  */
extern error_t __pthread_sigstate (struct __pthread *__restrict thread, int how,
				   const sigset_t *__restrict set,
				   sigset_t *__restrict oset,
				   int clear_pending);

/* If supported, check that MUTEX is locked by the caller.  */
extern int __pthread_mutex_checklocked (pthread_mutex_t *mtx);
\f

/* Default thread attributes.  */
extern struct __pthread_attr __pthread_default_attr;

/* Default barrier attributes.  */
extern const struct __pthread_barrierattr __pthread_default_barrierattr;

/* Default rdlock attributes.  */
extern const struct __pthread_rwlockattr __pthread_default_rwlockattr;

/* Default condition attributes.  */
extern const struct __pthread_condattr __pthread_default_condattr;

#endif /* pt-internal.h */
Commit	Line	Data
33574c17	1	/* Internal defenitions for pthreads library.
d614a753	2	Copyright (C) 2000-2020 Free Software Foundation, Inc.
33574c17 ST	3	This file is part of the GNU C Library.
	4
	5	The GNU C Library is free software; you can redistribute it and/or
ad2b41bf ST	6	modify it under the terms of the GNU Lesser General Public
	7	License as published by the Free Software Foundation; either
	8	version 2.1 of the License, or (at your option) any later version.
33574c17 ST	9
	10	The GNU C Library 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 GNU
ad2b41bf	13	Lesser General Public License for more details.
33574c17	14
ad2b41bf ST	15	You should have received a copy of the GNU Lesser General Public
ad2b41bf ST	16	License along with the GNU C Library; if not, see
5a82c748	17	<https://www.gnu.org/licenses/>. */
33574c17 ST	18
	19	#ifndef _PT_INTERNAL_H
	20	#define _PT_INTERNAL_H 1
	21
	22	#include <pthread.h>
	23	#include <stddef.h>
	24	#include <sched.h>
	25	#include <signal.h>
	26	#include <assert.h>
	27	#include <bits/types/res_state.h>
	28
	29	#include <atomic.h>
	30
	31	#include <pt-key.h>
	32
	33	#include <pt-sysdep.h>
	34	#include <pt-machdep.h>
	35
	36	#if IS_IN (libpthread)
	37	# include <ldsodefs.h>
	38	#endif
	39
12e166dd ST	40	#include <tls.h>
12e166dd ST	41
33574c17 ST	42	/* Thread state. */
	43	enum pthread_state
	44	{
	45	/* The thread is running and joinable. */
	46	PTHREAD_JOINABLE = 0,
	47	/* The thread is running and detached. */
	48	PTHREAD_DETACHED,
	49	/* A joinable thread exited and its return code is available. */
	50	PTHREAD_EXITED,
	51	/* The thread structure is unallocated and available for reuse. */
	52	PTHREAD_TERMINATED
	53	};
	54
	55	#ifndef PTHREAD_KEY_MEMBERS
	56	# define PTHREAD_KEY_MEMBERS
	57	#endif
	58
	59	#ifndef PTHREAD_SYSDEP_MEMBERS
	60	# define PTHREAD_SYSDEP_MEMBERS
	61	#endif
	62
33574c17 ST	63	/* This structure describes a POSIX thread. */
	64	struct __pthread
	65	{
	66	/* Thread ID. */
	67	pthread_t thread;
	68
	69	unsigned int nr_refs; /* Detached threads have a self reference only,
	70	while joinable threads have two references.
	71	These are used to keep the structure valid at
	72	thread destruction. Detaching/joining a thread
	73	drops a reference. */
	74
	75	/* Cancellation. */
	76	pthread_mutex_t cancel_lock; /* Protect cancel_xxx members. */
	77	void (cancel_hook) (void ); /* Called to unblock a thread blocking
	78	in a cancellation point (namely,
	79	__pthread_cond_timedwait_internal). */
	80	void *cancel_hook_arg;
	81	int cancel_state;
	82	int cancel_type;
	83	int cancel_pending;
33574c17 ST	84
	85	/* Thread stack. */
	86	void *stackaddr;
	87	size_t stacksize;
	88	size_t guardsize;
	89	int stack; /* Nonzero if the stack was allocated. */
	90
	91	/* Exit status. */
	92	void *status;
	93
	94	/* Thread state. */
	95	enum pthread_state state;
	96	pthread_mutex_t state_lock; /* Locks the state. */
	97	pthread_cond_t state_cond; /* Signalled when the state changes. */
	98
	99	/* Resolver state. */
	100	struct __res_state res_state;
	101
0c036123 ST	102	/* Indicates whether is a C11 thread created by thrd_creat. */
	103	bool c11;
	104
d482ebfa ST	105	/* Initial sigset for the thread. */
	106	sigset_t init_sigset;
	107
33574c17 ST	108	/* Thread context. */
	109	struct pthread_mcontext mcontext;
	110
	111	PTHREAD_KEY_MEMBERS
	112
	113	PTHREAD_SYSDEP_MEMBERS
	114
	115	tcbhead_t *tcb;
	116
	117	/* Queue links. Since PREVP is used to determine if a thread has been
	118	awaken, it must be protected by the queue lock. */
	119	struct __pthread next, *prevp;
	120	};
	121
	122	/* Enqueue an element THREAD on the queue HEAD. /
	123	static inline void
	124	__pthread_enqueue (struct __pthread *head, struct __pthread thread)
	125	{
	126	assert (thread->prevp == 0);
	127
	128	thread->next = *head;
	129	thread->prevp = head;
	130	if (*head)
	131	(*head)->prevp = &thread->next;
	132	*head = thread;
	133	}
	134
	135	/* Dequeue the element THREAD from the queue it is connected to. */
	136	static inline void
	137	__pthread_dequeue (struct __pthread *thread)
	138	{
	139	assert (thread);
	140	assert (thread->prevp);
	141
	142	if (thread->next)
	143	thread->next->prevp = thread->prevp;
	144	*thread->prevp = thread->next;
	145	thread->prevp = 0;
	146	}
	147
	148	/* Iterate over QUEUE storing each element in ELEMENT. */
	149	#define __pthread_queue_iterate(queue, element) \
	150	for (struct __pthread *__pdi_next = (queue); \
	151	((element) = __pdi_next) \
	152	&& ((__pdi_next = __pdi_next->next), \
	153	1); \
	154	)
	155
	156	/* Iterate over QUEUE dequeuing each element, storing it in
	157	ELEMENT. */
	158	#define __pthread_dequeuing_iterate(queue, element) \
	159	for (struct __pthread *__pdi_next = (queue); \
	160	((element) = __pdi_next) \
	161	&& ((__pdi_next = __pdi_next->next), \
	162	((element)->prevp = 0), \
	163	1); \
	164	)
	165
	166	/* The total number of threads currently active. */
	167	extern unsigned int __pthread_total;
	168
	169	/* The total number of thread IDs currently in use, or on the list of
	170	available thread IDs. */
	171	extern int __pthread_num_threads;
172
173	/* Concurrency hint. */
174	extern int __pthread_concurrency;
175
176	/* Array of __pthread structures and its lock. Indexed by the pthread
177	id minus one. (Why not just use the pthread id? Because some
178	brain-dead users of the pthread interface incorrectly assume that 0
179	is an invalid pthread id.) */
180	extern struct __pthread **__pthread_threads;
1d62a403	181	extern int __pthread_max_threads;
33574c17 ST	182	extern pthread_rwlock_t __pthread_threads_lock;
	183
	184	#define __pthread_getid(thread) \
1d62a403	185	({ struct __pthread *__t = NULL; \
33574c17	186	__pthread_rwlock_rdlock (&__pthread_threads_lock); \
1d62a403 ST	187	if (thread <= __pthread_max_threads) \
1d62a403 ST	188	__t = __pthread_threads[thread - 1]; \
33574c17 ST	189	__pthread_rwlock_unlock (&__pthread_threads_lock); \
	190	__t; })
	191
	192	#define __pthread_setid(thread, pthread) \
	193	__pthread_rwlock_wrlock (&__pthread_threads_lock); \
	194	__pthread_threads[thread - 1] = pthread; \
	195	__pthread_rwlock_unlock (&__pthread_threads_lock);
	196
	197	/* Similar to pthread_self, but returns the thread descriptor instead
	198	of the thread ID. */
	199	#ifndef _pthread_self
	200	extern struct __pthread *_pthread_self (void);
	201	#endif
a50efac1 ST	202
	203	/* Stores the stack of cleanup handlers for the thread. */
	204	extern __thread struct __pthread_cancelation_handler *__pthread_cleanup_stack;
33574c17 ST	205	\f
	206
	207	/* Initialize the pthreads library. */
	208	extern void ___pthread_init (void);
	209
	210	/* Internal version of pthread_create. Rather than return the new
	211	tid, we return the whole __pthread structure in PTHREAD. /
	212	extern int __pthread_create_internal (struct __pthread **__restrict pthread,
	213	const pthread_attr_t *__restrict attr,
	214	void (start_routine) (void *),
	215	void *__restrict arg);
	216
	217	/* Allocate a new thread structure and a pthread thread ID (but not a
	218	kernel thread or a stack). THREAD has one reference. */
	219	extern int __pthread_alloc (struct __pthread **thread);
	220
	221	/* Deallocate the thread structure. This is the dual of
	222	__pthread_alloc (N.B. it does not call __pthread_stack_dealloc nor
	223	__pthread_thread_terminate). THREAD loses one reference and is
	224	released if the reference counter drops to 0. */
	225	extern void __pthread_dealloc (struct __pthread *thread);
	226
	227
	228	/* Allocate a stack of size STACKSIZE. The stack base shall be
	229	returned in STACKADDR. /
	230	extern int __pthread_stack_alloc (void **stackaddr, size_t stacksize);
	231
	232	/* Deallocate the stack STACKADDR of size STACKSIZE. */
	233	extern void __pthread_stack_dealloc (void *stackaddr, size_t stacksize);
	234
	235
	236	/* Setup thread THREAD's context. */
	237	extern int __pthread_setup (struct __pthread *__restrict thread,
	238	void (entry_point) (struct __pthread ,
	239	void ()(void *),
	240	void *),
	241	void (start_routine) (void *),
	242	void *__restrict arg);
	243
	244
	245	/* Allocate a kernel thread (and any miscellaneous system dependent
	246	resources) for THREAD; it must not be placed on the run queue. */
	247	extern int __pthread_thread_alloc (struct __pthread *thread);
	248
	249	/* Start THREAD making it eligible to run. */
	250	extern int __pthread_thread_start (struct __pthread *thread);
	251
	252	/* Terminate the kernel thread associated with THREAD, and deallocate its
	253	stack as well as any other kernel resource associated with it.
	254	In addition, THREAD looses one reference.
	255
	256	This function can be called by any thread, including the target thread.
	257	Since some resources that are destroyed along the kernel thread are
	258	stored in thread-local variables, the conditions required for this
	259	function to behave correctly are a bit unusual : as long as the target
	260	thread hasn't been started, any thread can terminate it, but once it
	261	has started, no other thread can terminate it, so that thread-local
	262	variables created by that thread are correctly released. */
	263	extern void __pthread_thread_terminate (struct __pthread *thread);
	264
	265
	266	/* Called by a thread just before it calls the provided start
	267	routine. */
	268	extern void __pthread_startup (void);
269
270	/* Block THREAD. */
271	extern void __pthread_block (struct __pthread *thread);
272
273	/* Block THREAD until ABSTIME is reached. /
274	extern error_t __pthread_timedblock (struct __pthread *__restrict thread,
275	const struct timespec *__restrict abstime,
276	clockid_t clock_id);
277
e9644c20 ST	278	/* Block THREAD with interrupts. */
	279	extern error_t __pthread_block_intr (struct __pthread *thread);
	280
	281	/* Block THREAD until ABSTIME is reached, with interrupts. /
	282	extern error_t __pthread_timedblock_intr (struct __pthread *__restrict thread,
	283	const struct timespec *__restrict abstime,
	284	clockid_t clock_id);
	285
33574c17 ST	286	/* Wakeup THREAD. */
	287	extern void __pthread_wakeup (struct __pthread *thread);
	288
	289
	290	/* Perform a cancelation. The CANCEL_LOCK member of the given thread must
	291	be locked before calling this function, which must unlock it. */
	292	extern int __pthread_do_cancel (struct __pthread *thread);
	293
	294
	295	/* Initialize the thread specific data structures. THREAD must be the
	296	calling thread. */
	297	extern error_t __pthread_init_specific (struct __pthread *thread);
	298
	299	/* Call the destructors on all of the thread specific data in THREAD.
	300	THREAD must be the calling thread. */
	301	extern void __pthread_destroy_specific (struct __pthread *thread);
	302
	303
	304	/* Initialize newly create thread *THREAD's signal state data
	305	structures. */
	306	extern error_t __pthread_sigstate_init (struct __pthread *thread);
	307
	308	/* Destroy the signal state data structures associcated with thread
	309	THREAD. /
	310	extern void __pthread_sigstate_destroy (struct __pthread *thread);
	311
	312	/* Modify thread THREAD's signal state. /
	313	extern error_t __pthread_sigstate (struct __pthread *__restrict thread, int how,
	314	const sigset_t *__restrict set,
	315	sigset_t *__restrict oset,
	316	int clear_pending);
cd94860c ST	317
	318	/* If supported, check that MUTEX is locked by the caller. */
	319	extern int __pthread_mutex_checklocked (pthread_mutex_t *mtx);
33574c17 ST	320	\f
	321
	322	/* Default thread attributes. */
34f168fb	323	extern struct __pthread_attr __pthread_default_attr;
33574c17 ST	324
	325	/* Default barrier attributes. */
	326	extern const struct __pthread_barrierattr __pthread_default_barrierattr;
	327
33574c17 ST	328	/* Default rdlock attributes. */
	329	extern const struct __pthread_rwlockattr __pthread_default_rwlockattr;
	330
	331	/* Default condition attributes. */
	332	extern const struct __pthread_condattr __pthread_default_condattr;
	333
	334	#endif /* pt-internal.h */