Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
THRD_CREATE(3)		    Library Functions Manual		THRD_CREATE(3)

NAME
       call_once,    cnd_broadcast,    cnd_destroy,    cnd_init,   cnd_signal,
       cnd_timedwait,	 cnd_wait,    mtx_destroy,     mtx_init,     mtx_lock,
       mtx_timedlock,	mtx_trylock,  mtx_unlock,  thrd_create,	 thrd_current,
       thrd_detach, thrd_equal,	thrd_exit, thrd_join, thrd_sleep,  thrd_yield,
       tss_create, tss_delete, tss_get,	tss_set	-- C11 threads interface

LIBRARY
       library "libstdthreads"

SYNOPSIS
       #include	<threads.h>

       void
       call_once(once_flag *flag, void (*func)(void));

       int
       cnd_broadcast(cnd_t *cond);

       void
       cnd_destroy(cnd_t *cond);

       int
       cnd_init(cnd_t *cond);

       int
       cnd_signal(cnd_t	*cond);

       int
       cnd_timedwait(cnd_t   *	 restrict   cond,   mtx_t   *	restrict  mtx,
	   const struct	timespec * restrict ts);

       int
       cnd_wait(cnd_t *cond, mtx_t *mtx);

       void
       mtx_destroy(mtx_t *mtx);

       int
       mtx_init(mtx_t *mtx, int	type);

       int
       mtx_lock(mtx_t *mtx);

       int
       mtx_timedlock(mtx_t	       *	     restrict		  mtx,
	   const struct	timespec * restrict ts);

       int
       mtx_trylock(mtx_t *mtx);

       int
       mtx_unlock(mtx_t	*mtx);

       int
       thrd_create(thrd_t *thr,	int (*func)(void *), void *arg);

       thrd_t
       thrd_current(void);

       int
       thrd_detach(thrd_t thr);

       int
       thrd_equal(thrd_t thr0, thrd_t thr1);

       _Noreturn void
       thrd_exit(int res);

       int
       thrd_join(thrd_t	thr, int *res);

       int
       thrd_sleep(const		  struct	  timespec	    *duration,
	   struct timespec *remaining);

       void
       thrd_yield(void);

       int
       tss_create(tss_t	*key, void (*dtor)(void	*));

       void
       tss_delete(tss_t	key);

       void *
       tss_get(tss_t key);

       int
       tss_set(tss_t key, void *val);

DESCRIPTION
       As of ISO/IEC 9899:2011 ("ISO C11"), the	C standard includes an API for
       writing multithreaded applications.  Since POSIX.1 already  includes  a
       threading  API that is used by virtually	any multithreaded application,
       the interface provided by the C standard	can be considered superfluous.

       In this implementation, the threading  interface	 is  therefore	imple-
       mented  as  a  light-weight  layer  on top of existing interfaces.  The
       functions to which these	routines are mapped, are listed	in the follow-
       ing table.  Please refer	to the documentation of	the  POSIX  equivalent
       functions for more information.

	     Function		POSIX equivalent
	     call_once()	pthread_once(3)
	     cnd_broadcast()	pthread_cond_broadcast(3)
	     cnd_destroy()	pthread_cond_destroy(3)
	     cnd_init()		pthread_cond_init(3)
	     cnd_signal()	pthread_cond_signal(3)
	     cnd_timedwait()	pthread_cond_timedwait(3)
	     cnd_wait()		pthread_cond_wait(3)
	     mtx_destroy()	pthread_mutex_destroy(3)
	     mtx_init()		pthread_mutex_init(3)
	     mtx_lock()		pthread_mutex_lock(3)
	     mtx_timedlock()	pthread_mutex_timedlock(3)
	     mtx_trylock()	pthread_mutex_trylock(3)
	     mtx_unlock()	pthread_mutex_unlock(3)
	     thrd_create()	pthread_create(3)
	     thrd_current()	pthread_self(3)
	     thrd_detach()	pthread_detach(3)
	     thrd_equal()	pthread_equal(3)
	     thrd_exit()	pthread_exit(3)
	     thrd_join()	pthread_join(3)
	     thrd_sleep()	nanosleep(2)
	     thrd_yield()	pthread_yield(3)
	     tss_create()	pthread_key_create(3)
	     tss_delete()	pthread_key_delete(3)
	     tss_get()		pthread_getspecific(3)
	     tss_set()		pthread_setspecific(3)

DIFFERENCES WITH POSIX EQUIVALENTS
       The thrd_exit() function	returns	an integer value to the	thread calling
       thrd_join(), whereas the	pthread_exit() function	uses a pointer.

       The  mutex  created by mtx_init() can be	of type	mtx_plain or mtx_timed
       to distinguish between a	mutex  that  supports  mtx_timedlock().	  This
       type  can  be or'd with mtx_recursive to	create a mutex that allows re-
       cursive	acquisition.   These  properties  are	normally   set	 using
       pthread_mutex_init()'s attr parameter.

RETURN VALUES
       If   successful,	  the	cnd_broadcast(),   cnd_init(),	 cnd_signal(),
       cnd_timedwait(),	cnd_wait(), mtx_init(),	 mtx_lock(),  mtx_timedlock(),
       mtx_trylock(),	   mtx_unlock(),     thrd_create(),	thrd_detach(),
       thrd_equal(), thrd_join(),  thrd_sleep(),  tss_create()	and  tss_set()
       functions  return  thrd_success.	  Otherwise  an	error code will	be re-
       turned to indicate the error.

       The thrd_current() function  returns  the  thread  ID  of  the  calling
       thread.

       The  tss_get()  function	returns	the thread-specific data value associ-
       ated with the given key.	 If no thread-specific data value  is  associ-
       ated with key, then the value NULL is returned.

ERRORS
       The cnd_init() and thrd_create()	functions will fail if:

       thrd_nomem     The system has insufficient memory.

       The cnd_timedwait() and mtx_timedlock() functions will fail if:

       thrd_timedout  The  system time has reached or exceeded the time	speci-
		      fied in ts before	the operation could be completed.

       The mtx_trylock() function will fail if:

       thrd_busy      The mutex	is already locked.

       In all other cases, these functions may fail by returning general error
       code thrd_error.

SEE ALSO
       nanosleep(2), pthread(3)

STANDARDS
       These  functions	 are  expected	to  conform   to   ISO/IEC   9899:2011
       ("ISO C11").

HISTORY
       These functions appeared	in FreeBSD 10.0.

AUTHORS
       Ed Schouten <ed@FreeBSD.org>

FreeBSD	15.0		       December	26, 2011		THRD_CREATE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=thrd_create&manpath=FreeBSD+15.0-RELEASE+and+Ports>

home | help