Print this page 
11622 clean up rarer mandoc lint warnings
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man5/threads.5
          +++ new/usr/src/man/man5/threads.5
↓ open down ↓ 1 lines elided ↑ open up ↑ 
   2    2  .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3    3  .\" Copyright 2016 Joyent, Inc.
   4    4  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5    5  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6    6  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7    7  .TH THREADS 5 "Mar 27, 2016"
   8    8  .SH NAME
   9    9  threads, pthreads \- POSIX pthreads, c11, and illumos threads concepts
  10   10  .SH SYNOPSIS
  11   11  .SS "POSIX"
  12      -.LP
  13   12  .nf
  14   13  gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  15   14  .fi
  16   15  
  17   16  .LP
  18   17  .nf
  19   18  #include <pthread.h>
  20   19  .fi
  21   20  
  22   21  .SS "C11"
  23      -.LP
  24   22  .nf
  25   23  gcc -std=c11 -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  26   24  .fi
  27   25  
  28   26  .LP
  29   27  .nf
  30   28  #include <threads.h>
  31   29  .fi
  32   30  
  33   31  .SS "illumos"
  34      -.LP
  35   32  .nf
  36   33  gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  37   34  .fi
  38   35  
  39   36  .LP
  40   37  .nf
  41   38  #include <sched.h>
  42   39  .fi
  43   40  
  44   41  .LP
  45   42  .nf
  46   43  #include <thread.h>
  47   44  .fi
  48   45  
  49   46  .SH DESCRIPTION
  50      -.LP
  51   47  A thread is an independent source of execution within a process. Every process
  52   48  is created with a single thread, which calls the
  53   49  .B main
  54   50  function. A process may have multiple threads, all of which are scheduled
  55   51  independently by the system and may run concurrently. Threads within a process
  56   52  all use the same address space and as a result can access all data in the
  57   53  process; however, each thread is created with its own attributes and its own
  58   54  stack. When a thread is created, it inherits the signal mask of the thread which
  59   55  created it, but it has no pending signals.
  60   56  .sp
↓ open down ↓ 16 lines elided ↑ open up ↑ 
  77   73  synchronization may be necessary, for more information, see \fBmembar_ops\fR(3C).
  78   74  .LP
  79   75  POSIX, C11, and illumos threads each have their own implementation within
  80   76  \fBlibc\fR(3LIB). All implementations are interoperable, their functionality
  81   77  similar, and can be used within the same application. Only POSIX threads are
  82   78  guaranteed to be fully portable to other POSIX-compliant environments. C11
  83   79  threads are an optional part of ISO C11 and may not exist on every ISO C11
  84   80  platform. POSIX, C11, and illumos threads require different source and include
  85   81  files. See \fBSYNOPSIS\fR.
  86   82  .SS "Similarities"
  87      -.LP
  88   83  Most of the POSIX and illumos threading functions have counterparts with each
  89   84  other. POSIX function names, with the exception of the semaphore names, have a
  90   85  "\fBpthread\fR" prefix. Function names for similar POSIX and illumos functions
  91   86  have similar endings. Typically, similar POSIX and illumos functions have the
  92   87  same number and use of arguments.
  93   88  .SS "Differences"
  94      -.LP
  95   89  POSIX pthreads and illumos threads differ in the following ways:
  96   90  .RS +4
  97   91  .TP
  98   92  .ie t \(bu
  99   93  .el o
 100   94  POSIX threads are more portable.
 101   95  .RE
 102   96  .RS +4
 103   97  .TP
 104   98  .ie t \(bu
↓ open down ↓ 26 lines elided ↑ open up ↑ 
 131  125  illumos threads can be suspended and continued.
 132  126  .RE
 133  127  .RS +4
 134  128  .TP
 135  129  .ie t \(bu
 136  130  .el o
 137  131  illumos threads implement daemon threads, for whose demise the process does not
 138  132  wait.
 139  133  .RE
 140  134  .SS "Comparison to C11 Threads"
 141      -.LP
 142  135  C11 threads are not as functional as either POSIX or illumos threads. C11
 143  136  threads only support intra-process locking and do not have any form of
 144  137  readers/writer locking or semaphores. In general, POSIX threads will be more
 145  138  portable than C11 threads, all POSIX-compliant systems support pthreads;
 146  139  however, not all C environments support C11 Threads.
 147  140  .sp
 148  141  .LP
 149  142  In addition to lacking other common synchronization primitives, the ISO/IEC
 150  143  standard for C11 threads does not have rich error semantics. In an effort to not
 151  144  extend the set of error numbers standardized in ISO/IEC C11, none of the
 152  145  routines set errno and instead multiple distinguishable errors, aside from the
 153  146  equivalent to ENOMEM and EBUSY, are all squashed into one. As such, users of the
 154  147  platform are encouraged to use POSIX threads, unless a portability concern
 155  148  dictates otherwise.
 156  149  
 157  150  .SH FUNCTION COMPARISON
 158      -.LP
 159  151  The following table compares the POSIX pthreads, C11 threads, and illumos
 160  152  threads functions.  When a comparable interface is not available either in POSIX
 161  153  pthreads, C11 threads  or illumos threads, a hyphen (\fB-\fR) appears in the
 162  154  column.
 163  155  .SS "Functions Related to Creation"
 164  156  
 165  157  .TS
 166  158  l l l
 167  159  l l l .
 168  160  \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
↓ open down ↓ 160 lines elided ↑ open up ↑ 
 329  321  
 330  322  .SS "Functions Related to Semaphores"
 331  323  
 332  324  .TS
 333  325  l l l
 334  326  l l l .
 335  327  \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 336  328  \fBsem_init()\fR        \fBsema_init()\fR       \fB-\fR
 337  329  \fBsem_open()\fR        \fB-\fR \fB-\fR
 338  330  \fBsem_close()\fR       \fB-\fR \fB-\fR
 339      -\fBsem_wait()\fR        \fBsema_wait()\ \fB-\fR
      331 +\fBsem_wait()\fR        \fBsema_wait()\fR       \fB-\fR
 340  332  \fBsem_trywait()\fR     \fBsema_trywait()\fR    \fB-\fR
 341  333  \fBsem_post()\fR        \fBsema_post()\fR       \fB-\fR
 342  334  \fBsem_getvalue()\fR    \fB-\fR \fB-\fR
 343  335  \fBsem_unlink()\fR      \fB-\fR \fB-\fR
 344  336  \fBsem_destroy()\fR     \fBsema_destroy()\fR    \fB-\fR
 345  337  .TE
 346  338  
 347  339  .SS "Functions Related to fork(\|) Clean Up"
 348  340  
 349  341  .TS
↓ open down ↓ 16 lines elided ↑ open up ↑ 
 366  358  
 367  359  .TS
 368  360  l l l
 369  361  l l l .
 370  362  \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 371  363  \fB-\fR \fBthr_stksegment()\fR  \fB-\fR
 372  364  .TE
 373  365  
 374  366  .SH LOCKING
 375  367  .SS "Synchronization"
 376      -.LP
 377  368  Multithreaded behavior is asynchronous, and therefore,  optimized for
 378  369  concurrent and parallel processing. As threads, always from within the same
 379  370  process and  sometimes from multiple processes, share global data with each
 380  371  other, they are not guaranteed exclusive access to the shared data at any point
 381  372  in time. Securing mutually exclusive access to shared data requires
 382  373  synchronization among the threads. Both POSIX and illumos implement four
 383  374  synchronization mechanisms: mutexes, condition variables, reader/writer locking
 384  375  (\fIoptimized frequent-read occasional-write mutex\fR), and semaphores, where as
 385  376  C11 threads only implement two mechanisms: mutexes and condition variables.
 386  377  .sp
 387  378  .LP
 388  379  Synchronizing multiple threads diminishes their concurrency. The coarser the
 389  380  grain of synchronization, that is, the larger the block of code that is locked,
 390  381  the lesser the concurrency.
 391  382  .SS "MT \fBfork()\fR"
 392      -.LP
 393  383  If a threads program calls \fBfork\fR(2), it implicitly calls \fBfork1\fR(2),
 394  384  which replicates only the calling thread. Should there be any outstanding
 395  385  mutexes throughout the process, the application should call
 396  386  \fBpthread_atfork\fR(3C) to wait for and acquire those mutexes prior to calling
 397  387  \fBfork()\fR.
 398  388  .SH SCHEDULING
 399  389  .SS "POSIX Threads"
 400      -.LP
 401  390  illumos supports the following three POSIX scheduling policies:
 402  391  .sp
 403  392  .ne 2
 404  393  .na
 405  394  \fB\fBSCHED_OTHER\fR\fR
 406  395  .ad
 407  396  .RS 15n
 408  397  Traditional Timesharing scheduling policy. It is based on the timesharing (TS)
 409  398  scheduling class.
 410  399  .RE
↓ open down ↓ 50 lines elided ↑ open up ↑ 
 461  450  .ne 2
 462  451  .na
 463  452  \fB\fBSCHED_FX\fR\fR
 464  453  .ad
 465  454  .RS 13n
 466  455  Threads are scheduled according to the Fixed-Priority Class (FX) policy as
 467  456  described in \fBpriocntl\fR(2).
 468  457  .RE
 469  458  
 470  459  .SS "illumos Threads"
 471      -.LP
 472  460  Only scheduling policy supported is \fBSCHED_OTHER\fR, which is timesharing,
 473  461  based on the \fBTS\fR scheduling class.
 474  462  .SH ERRORS
 475      -.LP
 476  463  In a multithreaded application, \fBEINTR\fR can be returned from blocking
 477  464  system calls when another thread calls \fBforkall\fR(2).
 478  465  .SH USAGE
 479  466  .SS "\fB-mt\fR compiler option"
 480      -.LP
 481  467  The \fB-mt\fR compiler option compiles and links for multithreaded code. It
 482  468  compiles source files with \(mi\fBD_REENTRANT\fR and augments the set of
 483  469  support libraries properly.
 484  470  .sp
 485  471  .LP
 486  472  Users of other compilers such as gcc and clang should manually set
 487  473  \(mi\fBD_REENTRANT\fR on the compilation line. There are no other libraries or
 488  474  flags necessary.
 489  475  .SH ATTRIBUTES
 490      -.LP
 491  476  See \fBattributes\fR(5) for descriptions of the following attributes:
 492  477  .sp
 493  478  
 494  479  .sp
 495  480  .TS
 496  481  box;
 497  482  c | c
 498  483  l | l .
 499  484  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 500  485  _
 501  486  MT-Level        MT-Safe, Fork 1-Safe
 502  487  .TE
 503  488  
 504  489  .SH SEE ALSO
 505      -.LP
 506  490  \fBcrle\fR(1), \fBfork\fR(2), \fBpriocntl\fR(2), \fBlibpthread\fR(3LIB),
 507  491  \fBlibrt\fR(3LIB), \fBlibthread\fR(3LIB), \fBpthread_atfork\fR(3C),
 508  492  \fBpthread_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
 509  493  .sp
 510  494  .LP
 511  495  \fILinker and Libraries Guide\fR
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX