11622 clean up rarer mandoc lint warnings

   1 THREADS(5)            Standards, Environments, and Macros           THREADS(5)
   2 
   3 
   4 
   5 NAME
   6        threads, pthreads - POSIX pthreads, c11, and illumos threads concepts
   7 
   8 SYNOPSIS
   9    POSIX
  10        gcc -D_REENTRANT [ flag... ] file... [ library... ]
  11 
  12 
  13        #include <pthread.h>
  14 
  15 
  16    C11
  17        gcc -std=c11 -D_REENTRANT [ flag... ] file... [ library... ]
  18 
  19 
  20        #include <threads.h>
  21 
  22 
  23    illumos
  24        gcc -D_REENTRANT [ flag... ] file... [ library... ]
  25 
  26 
  27        #include <sched.h>
  28 
  29 
  30        #include <thread.h>
  31 
  32 
  33 DESCRIPTION
  34        A thread is an independent source of execution within a process. Every
  35        process is created with a single thread, which calls the main function.
  36        A process may have multiple threads, all of which are scheduled
  37        independently by the system and may run concurrently. Threads within a
  38        process all use the same address space and as a result can access all
  39        data in the process; however, each thread is created with its own
  40        attributes and its own stack. When a thread is created, it inherits the
  41        signal mask of the thread which created it, but it has no pending
  42        signals.
  43 
  44 
  45        All threads of execution have their own, independent life time, though
  46        it is ultimately bounded by the life time of the process. If the
  47        process terminates for any reason, whether due to a call to exit(3C),
  48        the receipt of a fatal signal, or some other reason, then all threads
  49        within the process are terminated. Threads may themselves exit and
  50        status information of them may be obtained, for more information, see
  51        the pthread_detach(3C), pthread_join(3C), and pthread_exit(3C)
  52        functions, and their equivalents as described in the tables later on in
  53        the manual.
  54 
  55 
  56        Most hardware platforms do not have any special synchronization for
  57        data objects which may be accessed concurrently from multiple threads
  58        of execution. To avoid such problems, programs may use atomic
  59        operations (see atomic_ops(3C)) and locking primitives, such as
  60        mutexes, readers/writer locks, condition variables, and semaphores.
  61        Note, that depending on the hardware platform, memory synchronization
  62        may be necessary, for more information, see membar_ops(3C).
  63 
  64        POSIX, C11, and illumos threads each have their own implementation
  65        within libc(3LIB). All implementations are interoperable, their
  66        functionality similar, and can be used within the same application.
  67        Only POSIX threads are guaranteed to be fully portable to other POSIX-
  68        compliant environments. C11 threads are an optional part of ISO C11 and
  69        may not exist on every ISO C11 platform. POSIX, C11, and illumos
  70        threads require different source and include files. See SYNOPSIS.
  71 
  72    Similarities
  73        Most of the POSIX and illumos threading functions have counterparts
  74        with each other. POSIX function names, with the exception of the
  75        semaphore names, have a "pthread" prefix. Function names for similar
  76        POSIX and illumos functions have similar endings. Typically, similar
  77        POSIX and illumos functions have the same number and use of arguments.
  78 
  79    Differences
  80        POSIX pthreads and illumos threads differ in the following ways:
  81 
  82            o      POSIX threads are more portable.
  83 
  84            o      POSIX threads establish characteristics  for each thread
  85                   according to configurable attribute objects.
  86 
  87            o      POSIX pthreads implement thread cancellation.
  88 
  89            o      POSIX pthreads enforce scheduling algorithms.
  90 
  91            o      POSIX pthreads allow for clean-up handlers for fork(2)
  92                   calls.
  93 
  94            o      illumos threads can be suspended and continued.
  95 
  96            o      illumos threads implement daemon threads, for whose demise
  97                   the process does not wait.
  98 
  99    Comparison to C11 Threads
 100        C11 threads are not as functional as either POSIX or illumos threads.
 101        C11 threads only support intra-process locking and do not have any form
 102        of readers/writer locking or semaphores. In general, POSIX threads will
 103        be more portable than C11 threads, all POSIX-compliant systems support
 104        pthreads; however, not all C environments support C11 Threads.
 105 
 106 
 107        In addition to lacking other common synchronization primitives, the
 108        ISO/IEC standard for C11 threads does not have rich error semantics. In
 109        an effort to not extend the set of error numbers standardized in
 110        ISO/IEC C11, none of the routines set errno and instead multiple
 111        distinguishable errors, aside from the equivalent to ENOMEM and EBUSY,
 112        are all squashed into one. As such, users of the platform are
 113        encouraged to use POSIX threads, unless a portability concern dictates
 114        otherwise.
 115 
 116 
 117 FUNCTION COMPARISON
 118        The following table compares the POSIX pthreads, C11 threads, and
 119        illumos threads functions.  When a comparable interface is not
 120        available either in POSIX pthreads, C11 threads  or illumos threads, a
 121        hyphen (-) appears in the column.
 122 
 123    Functions Related to Creation
 124 
 125        POSIX                            illumos           C11
 126        pthread_create()                 thr_create()      thrd_create()
 127        pthread_attr_init()              -                 -
 128        pthread_attr_setdetachstate()    -                 -
 129        pthread_attr_getdetachstate()    -                 -
 130        pthread_attr_setinheritsched()   -                 -
 131        pthread_attr_getinheritsched()   -                 -
 132        pthread_attr_setschedparam()     -                 -
 133        pthread_attr_getschedparam()     -                 -
 134        pthread_attr_setschedpolicy()    -                 -
 135        pthread_attr_getschedpolicy()    -                 -
 136        pthread_attr_setscope()          -                 -
 137        pthread_attr_getscope()          -                 -
 138        pthread_attr_setstackaddr()      -                 -
 139        pthread_attr_getstackaddr()      -                 -
 140        pthread_attr_setstacksize()      -                 -
 141        pthread_attr_getstacksize()      -                 -
 142        pthread_attr_getguardsize()      -                 -
 143        pthread_attr_setguardsize()      -                 -
 144        pthread_attr_destroy()           -                 -
 145        -                                thr_min_stack()   -
 146 
 147 
 148    Functions Related to Exit
 149 
 150        POSIX              illumos      C11
 151        pthread_exit()     thr_exit()   thrd_exit()
 152        pthread_join()     thr_join()   thrd_join()
 153        pthread_detach()   -            thrd_detach()
 154 
 155 
 156    Functions Related to Thread Specific Data
 157 
 158        POSIX                   illumos             C11
 159        pthread_key_create()    thr_keycreate()     tss_create()
 160        pthread_setspecific()   thr_setspecific()   tss_set()
 161        pthread_getspecific()   thr_getspecific()   tss_get()
 162        pthread_key_delete()    -                   tss_delete()
 163 
 164 
 165    Functions Related to Signals
 166 
 167        POSIX               illumos            C11
 168        pthread_sigmask()   thr_sigsetmask()   -
 169        pthread_kill()      thr_kill()         -
 170 
 171 
 172    Functions Related to IDs
 173 
 174        POSIX             illumos      c11
 175        pthread_self()    thr_self()   thrd_current()
 176        pthread_equal()   -            thrd_equal()
 177        -                 thr_main()   -
 178 
 179 
 180    Functions Related to Scheduling
 181 
 182        POSIX                      illumos                C11
 183        -                          thr_yield()            thrd_yield()
 184        -                          thr_suspend()          -
 185        -                          thr_continue()         -
 186        pthread_setconcurrency()   thr_setconcurrency()   -
 187        pthread_getconcurrency()   thr_getconcurrency()   -
 188        pthread_setschedparam()    thr_setprio()          -
 189        pthread_setschedprio()     thr_setprio()          -
 190        pthread_getschedparam()    thr_getprio()          -
 191 
 192 
 193    Functions Related to Cancellation
 194 
 195        POSIX                      illumos   C11
 196        pthread_cancel()           -         -
 197        pthread_setcancelstate()   -         -
 198        pthread_setcanceltype()    -         -
 199        pthread_testcancel()       -         -
 200        pthread_cleanup_pop()      -         -
 201        pthread_cleanup_push()     -         -
 202 
 203 
 204    Functions Related to Mutexes
 205 
 206        POSIX                                illumos           c11
 207        pthread_mutex_init()                 mutex_init()      mtx_init()
 208        pthread_mutexattr_init()             -                 -
 209        pthread_mutexattr_setpshared()       -                 -
 210        pthread_mutexattr_getpshared()       -                 -
 211        pthread_mutexattr_setprotocol()      -                 -
 212        pthread_mutexattr_getprotocol()      -                 -
 213        pthread_mutexattr_setprioceiling()   -                 -
 214        pthread_mutexattr_getprioceiling()   -                 -
 215        pthread_mutexattr_settype()          -                 -
 216        pthread_mutexattr_gettype()          -                 -
 217        pthread_mutexattr_setrobust()        -                 -
 218        pthread_mutexattr_getrobust()        -                 -
 219        pthread_mutexattr_destroy()          -                 mtx_destroy()
 220        pthread_mutex_setprioceiling()       -                 -
 221        pthread_mutex_getprioceiling()       -                 -
 222        pthread_mutex_lock()                 mutex_lock()      mtx_lock()
 223        pthread_mutex_timedlock()            -                 mtx_timedlock()
 224        pthread_mutex_trylock()              mutex_trylock()   mtx_trylock()
 225        pthread_mutex_unlock()               mutex_unlock()    mtx_unlock()
 226        pthread_mutex_destroy()              mutex_destroy()   mtx_destroy()
 227 
 228 
 229    Functions Related to Condition Variables
 230 
 231        POSIX                           illumos            C11
 232        pthread_cond_init()             cond_init()        cnd_init()
 233        pthread_condattr_init()         -                  -
 234        pthread_condattr_setpshared()   -                  -
 235        pthread_condattr_getpshared()   -                  -
 236        pthread_condattr_destroy()      -                  -
 237        pthread_cond_wait()             cond_wait()        cnd_wait()
 238        pthread_cond_timedwait()        cond_timedwait()   cond_timedwait()
 239        pthread_cond_signal()           cond_signal()      cnd_signal()
 240        pthread_cond_broadcast()        cond_broadcast()   cnd_broadcast()
 241        pthread_cond_destroy()          cond_destroy()     cnd_destroy()
 242 
 243 
 244    Functions Related to Reader/Writer Locking
 245 
 246        POSIX                             illumos            C11
 247        pthread_rwlock_init()             rwlock_init()      -
 248        pthread_rwlock_rdlock()           rw_rdlock()        -
 249        pthread_rwlock_tryrdlock()        rw_tryrdlock()     -
 250        pthread_rwlock_wrlock()           rw_wrlock()        -
 251        pthread_rwlock_trywrlock()        rw_trywrlock()     -
 252        pthread_rwlock_unlock()           rw_unlock()        -
 253        pthread_rwlock_destroy()          rwlock_destroy()   -
 254        pthread_rwlockattr_init()         -                  -
 255        pthread_rwlockattr_destroy()      -                  -
 256        pthread_rwlockattr_getpshared()   -                  -
 257        pthread_rwlockattr_setpshared()   -                  -
 258 
 259 
 260    Functions Related to Semaphores
 261 
 262        POSIX            illumos          C11
 263        sem_init()       sema_init()      -
 264        sem_open()       -                -
 265        sem_close()      -                -
 266        sem_wait()       sema_wait()      -
 267        sem_trywait()    sema_trywait()   -
 268        sem_post()       sema_post()      -
 269        sem_getvalue()   -                -
 270        sem_unlink()     -                -
 271        sem_destroy()    sema_destroy()   -
 272 
 273 
 274    Functions Related to fork() Clean Up
 275 
 276        POSIX              illumos   C11
 277        pthread_atfork()   -         -
 278 
 279 
 280    Functions Related to Limits
 281 
 282        POSIX            illumos   C11
 283        pthread_once()   -         call_once()
 284 
 285 
 286    Functions Related to Debugging
 287 
 288        POSIX   illumos            C11
 289        -       thr_stksegment()   -
 290 
 291 
 292 LOCKING
 293    Synchronization
 294        Multithreaded behavior is asynchronous, and therefore,  optimized for
 295        concurrent and parallel processing. As threads, always from within the
 296        same process and  sometimes from multiple processes, share global data
 297        with each other, they are not guaranteed exclusive access to the shared
 298        data at any point in time. Securing mutually exclusive access to shared
 299        data requires synchronization among the threads. Both POSIX and illumos
 300        implement four synchronization mechanisms: mutexes, condition
 301        variables, reader/writer locking (optimized frequent-read occasional-
 302        write mutex), and semaphores, where as C11 threads only implement two
 303        mechanisms: mutexes and condition variables.
 304 
 305 
 306        Synchronizing multiple threads diminishes their concurrency. The
 307        coarser the grain of synchronization, that is, the larger the block of
 308        code that is locked, the lesser the concurrency.
 309 
 310    MT fork()
 311        If a threads program calls fork(2), it implicitly calls fork1(2), which
 312        replicates only the calling thread. Should there be any outstanding
 313        mutexes throughout the process, the application should call
 314        pthread_atfork(3C) to wait for and acquire those mutexes prior to
 315        calling fork().
 316 
 317 SCHEDULING
 318    POSIX Threads
 319        illumos supports the following three POSIX scheduling policies:
 320 
 321        SCHED_OTHER
 322                       Traditional Timesharing scheduling policy. It is based
 323                       on the timesharing (TS) scheduling class.
 324 
 325 
 326        SCHED_FIFO
 327                       First-In-First-Out scheduling policy. Threads scheduled
 328                       to this policy, if not preempted by a higher priority,
 329                       will proceed until completion. Such threads are in real-
 330                       time (RT) scheduling class. The calling process must
 331                       have a effective user ID of 0.
 332 
 333 
 334        SCHED_RR
 335                       Round-Robin scheduling policy. Threads scheduled to this
 336                       policy, if not preempted by a higher priority, will
 337                       execute for a time period determined by the system. Such
 338                       threads are in real-time (RT) scheduling class and the
 339                       calling process must have a effective user ID of 0.
 340 
 341 
 342 
 343        In addition to the POSIX-specified scheduling policies above, illumos
 344        also supports these scheduling policies:
 345 
 346        SCHED_IA
 347                     Threads are scheduled according to the Inter-Active Class
 348                     (IA) policy as described in priocntl(2).
 349 
 350 
 351        SCHED_FSS
 352                     Threads are scheduled according to the Fair-Share Class
 353                     (FSS) policy as described in priocntl(2).
 354 
 355 
 356        SCHED_FX
 357                     Threads are scheduled according to the Fixed-Priority
 358                     Class (FX) policy as described in priocntl(2).
 359 
 360 
 361    illumos Threads
 362        Only scheduling policy supported is SCHED_OTHER, which is timesharing,
 363        based on the TS scheduling class.
 364 
 365 ERRORS
 366        In a multithreaded application, EINTR can be returned from blocking
 367        system calls when another thread calls forkall(2).
 368 
 369 USAGE
 370    -mt compiler option
 371        The -mt compiler option compiles and links for multithreaded code. It
 372        compiles source files with -D_REENTRANT and augments the set of support
 373        libraries properly.
 374 
 375 
 376        Users of other compilers such as gcc and clang should manually set
 377        -D_REENTRANT on the compilation line. There are no other libraries or
 378        flags necessary.
 379 
 380 ATTRIBUTES
 381        See attributes(5) for descriptions of the following attributes:
 382 
 383 
 384 
 385 
 386        +---------------+----------------------+
 387        |ATTRIBUTE TYPE |   ATTRIBUTE VALUE    |
 388        +---------------+----------------------+
 389        |MT-Level       | MT-Safe, Fork 1-Safe |
 390        +---------------+----------------------+
 391 
 392 SEE ALSO
 393        crle(1), fork(2), priocntl(2), libpthread(3LIB), librt(3LIB),
 394        libthread(3LIB), pthread_atfork(3C), pthread_create(3C), attributes(5),
 395        standards(5)
 396 
 397 
 398        Linker and Libraries Guide
 399 
 400 
 401 
 402                                 March 27, 2016                      THREADS(5)
--- EOF ---