home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / README.threads < prev    next >
Text File  |  2000-02-25  |  13KB  |  337 lines
  1. NOTE: This documentation describes the style of threading that was
  2. available in 5.005.  Perl v5.6 also has the early beginnings of
  3. interpreter-based threads support (which is what will be enabled by
  4. default when you simply ask for -Dusethreads).  However, be advised
  5. that interpreter threads cannot as yet be created from the Perl level
  6. yet.  If you're looking to create threads from within Perl, chances
  7. are you _don't_ want interpreter threads, but want the older support
  8. for threads described below, enabled with:
  9.  
  10.     sh Configure -Dusethreads -Duse5005threads
  11.  
  12. The rest of this document only applies to the use5005threads style of
  13. threads.
  14. ---------------------------------------------------------------------------
  15.  
  16. Support for threading is still in the highly experimental stages.  There
  17. are known race conditions that show up under high contention on SMP
  18. machines.  Internal implementation is still subject to changes.
  19. It is not recommended for production use at this time.
  20.  
  21. ---------------------------------------------------------------------------
  22.  
  23. Building
  24.  
  25. If your system is in the following list you should be able to just:
  26.  
  27.     ./Configure -Dusethreads -Duse5005threads -des
  28.     make
  29.  
  30. and ignore the rest of this "Building" section.  If not, continue
  31. from the "Problems" section.
  32.  
  33.     * Linux 2.* (with the LinuxThreads library installed:
  34.       that's the linuxthreads and linuxthreads-devel RPMs
  35.       for RedHat)
  36.  
  37.     * Tru64 UNIX (formerly Digital UNIX formerly DEC OSF/1)
  38.       (see additional note below)
  39.  
  40.     * Solaris 2.* for recentish x (2.5 is OK)
  41.  
  42.     * IRIX 6.2 or newer. 6.2 will require a few OS patches.
  43.       IMPORTANT: Without patch 2401 (or its replacement),
  44.       a kernel bug in IRIX 6.2 will cause your machine to
  45.       panic and crash when running threaded perl.
  46.       IRIX 6.3 and up should be OK. See lower down for patch details.
  47.  
  48.     * AIX 4.1.5 or newer.
  49.  
  50.     * FreeBSD 2.2.8 or newer.
  51.  
  52.     * OpenBSD
  53.  
  54.     * NeXTstep, OpenStep
  55.  
  56.     * OS/2
  57.  
  58.     * DOS DJGPP
  59.  
  60.     * VM/ESA
  61.  
  62. ---------------------------------------------------------------------------
  63.  
  64. Problems
  65.  
  66. If the simple way doesn't work or you are using another platform which
  67. you believe supports POSIX.1c threads then read on.  Additional
  68. information may be in a platform-specific "hints" file in the hints/
  69. subdirectory.
  70.  
  71. On platforms that use Configure to build perl, omit the -d from your
  72. ./Configure arguments. For example, use:
  73.  
  74.     ./Configure -Dusethreads -Duse5005threads
  75.  
  76. When Configure prompts you for ccflags, insert any other arguments in
  77. there that your compiler needs to use POSIX threads (-D_REENTRANT,
  78. -pthreads, -threads, -pthread, -thread, are good guesses). When
  79. Configure prompts you for linking flags, include any flags required
  80. for threading (usually nothing special is required here).  Finally,
  81. when Configure prompts you for libraries, include any necessary
  82. libraries (e.g. -lpthread).  Pay attention to the order of libraries.
  83. It is probably necessary to specify your threading library *before*
  84. your standard C library, e.g.  it might be necessary to have -lpthread
  85. -lc, instead of -lc -lpthread.  You may also need to use -lc_r instead
  86. of -lc.
  87.  
  88. Once you have specified all your compiler flags, you can have Configure
  89. accept all the defaults for the remainder of the session by typing  &-d
  90. at any Configure prompt.
  91.  
  92. Some additional notes (some of these may be obsolete now, other items
  93. may be handled automatically):
  94.  
  95. For Digital Unix 4.x:
  96.     Add -pthread to ccflags
  97.     Add -pthread to ldflags
  98.     Add -lpthread -lc_r to lddlflags
  99.  
  100.     For some reason, the extra includes for pthreads make Digital UNIX
  101.     complain fatally about the sbrk() delcaration in perl's malloc.c
  102.     so use the native malloc, e.g.  sh Configure -Uusemymalloc, or
  103.     manually edit your config.sh as follows:
  104.     Change usemymalloc to n
  105.     Zap mallocobj and mallocsrc (foo='')
  106.     Change d_mymalloc to undef
  107.  
  108. For Digital Unix 3.x (Formerly DEC OSF/1):
  109.     Add -DOLD_PTHREADS_API to ccflags
  110.     If compiling with the GNU cc compiler, remove -threads from ccflags
  111.  
  112.     (The following should be done automatically if you call Configure
  113.       with the -Dusethreads option).
  114.     Add -lpthread -lmach -lc_r to libs (in the order specified).
  115.  
  116. For IRIX:
  117.     (This should all be done automatically by the hint file).
  118.     Add -lpthread to libs
  119.     For IRIX 6.2, you have to have the following patches installed:
  120.     1404 Irix 6.2 Posix 1003.1b man pages
  121.     1645 IRIX 6.2 & 6.3 POSIX header file updates
  122.     2000 Irix 6.2 Posix 1003.1b support modules
  123.     2254 Pthread library fixes
  124.     2401 6.2 all platform kernel rollup
  125.     IMPORTANT: Without patch 2401, a kernel bug in IRIX 6.2 will
  126.     cause your machine to panic and crash when running threaded perl.
  127.     IRIX 6.3 and up should be OK.
  128.  
  129.     For IRIX 6.3 and 6.4 the pthreads should work out of the box.
  130.     Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
  131.     pthreads patches information.
  132.  
  133. For AIX:
  134.     (This should all be done automatically by the hint file).
  135.     Change cc to xlc_r or cc_r.
  136.     Add -DNEED_PTHREAD_INIT to ccflags and cppflags
  137.     Add -lc_r to libswanted
  138.     Change -lc in lddflags to be -lpthread -lc_r -lc
  139.  
  140. For Win32:
  141.     See README.win32, and the notes at the beginning of win32/Makefile
  142.     or win32/makefile.mk.
  143.  
  144. Now you can do a
  145.     make
  146.  
  147. When you succeed in compiling and testing ("make test" after your
  148. build) a threaded Perl in a platform previosuly unknown to support
  149. threaded perl, please let perlbug@perl.com know about your victory.
  150. Explain what you did in painful detail.
  151.  
  152. ---------------------------------------------------------------------------
  153.  
  154. O/S specific bugs
  155.  
  156. Irix 6.2:  See the Irix warning above.
  157.  
  158. LinuxThreads 0.5 has a bug which can cause file descriptor 0 to be
  159. closed after a fork() leading to many strange symptoms. Version 0.6
  160. has this fixed but the following patch can be applied to 0.5 for now:
  161.  
  162. ----------------------------- cut here -----------------------------
  163. --- linuxthreads-0.5/pthread.c.ORI    Mon Oct  6 13:55:50 1997
  164. +++ linuxthreads-0.5/pthread.c    Mon Oct  6 13:57:24 1997
  165. @@ -312,8 +312,10 @@
  166.    free(pthread_manager_thread_bos);
  167.    pthread_manager_thread_bos = pthread_manager_thread_tos = NULL;
  168.    /* Close the two ends of the pipe */
  169. -  close(pthread_manager_request);
  170. -  close(pthread_manager_reader);
  171. +  if (pthread_manager_request >= 0) {
  172. +    close(pthread_manager_request);
  173. +    close(pthread_manager_reader);
  174. +  }
  175.    pthread_manager_request = pthread_manager_reader = -1;
  176.    /* Update the pid of the main thread */
  177.    self->p_pid = getpid();
  178. ----------------------------- cut here -----------------------------
  179.  
  180.  
  181. Building the Thread extension
  182.  
  183. The Thread extension is now part of the main perl distribution tree.
  184. If you did Configure -Dusethreads -Duse5005threads then it will have been
  185. added to the list of extensions automatically.
  186.  
  187. You can try some of the tests with
  188.     cd ext/Thread
  189.     perl create.t
  190.     perl join.t
  191.     perl lock.t
  192.     perl io.t
  193. etc.
  194. The io one leaves a thread reading from the keyboard on stdin so
  195. as the ping messages appear you can type lines and see them echoed.
  196.  
  197. Try running the main perl test suite too. There are known
  198. failures for some of the DBM/DB extensions (if their underlying
  199. libraries were not compiled to be thread-aware).
  200.  
  201. ---------------------------------------------------------------------------
  202.  
  203. Bugs
  204.  
  205. * FAKE_THREADS should produce a working perl but the Thread
  206. extension won't build with it yet.  (FAKE_THREADS has not been
  207. tested at all in recent times.)
  208.  
  209. * There may still be races where bugs show up under contention.
  210.  
  211. ---------------------------------------------------------------------------
  212.  
  213. Debugging
  214.  
  215. Use the -DS command-line option to turn on debugging of the
  216. multi-threading code. Under Linux, that also turns on a quick
  217. hack I did to grab a bit of extra information from segfaults.
  218. If you have a fancier gdb/threads setup than I do then you'll
  219. have to delete the lines in perl.c which say
  220.     #if defined(DEBUGGING) && defined(USE_THREADS) && defined(__linux__)
  221.         DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
  222.     #endif
  223.  
  224. ---------------------------------------------------------------------------
  225.  
  226. Background
  227.  
  228. Some old globals (e.g. stack_sp, op) and some old per-interpreter
  229. variables (e.g. tmps_stack, cxstack) move into struct thread.
  230. All fields of struct thread which derived from original perl
  231. variables have names of the form Tfoo. For example, stack_sp becomes
  232. the field Tstack_sp of struct thread. For those fields which moved
  233. from original perl, thread.h does
  234.     #define foo (thr->Tfoo)
  235. This means that all functions in perl which need to use one of these
  236. fields need an (automatic) variable thr which points at the current
  237. thread's struct thread. For pp_foo functions, it is passed around as
  238. an argument, for other functions they do
  239.     dTHR;
  240. which declares and initialises thr from thread-specific data
  241. via pthread_getspecific. If a function fails to compile with an
  242. error about "no such variable thr", it probably just needs a dTHR
  243. at the top.
  244.  
  245.  
  246. Fake threads
  247.  
  248. For FAKE_THREADS, thr is a global variable and perl schedules threads
  249. by altering thr in between appropriate ops. The next and prev fields
  250. of struct thread keep all fake threads on a doubly linked list and
  251. the next_run and prev_run fields keep all runnable threads on a
  252. doubly linked list. Mutexes are stubs for FAKE_THREADS. Condition
  253. variables are implemented as a list of waiting threads.
  254.  
  255.  
  256. Mutexes and condition variables
  257.  
  258. The API is via macros MUTEX_{INIT,LOCK,UNLOCK,DESTROY} and
  259. COND_{INIT,WAIT,SIGNAL,BROADCAST,DESTROY}.
  260.  
  261. A mutex is only required to be a simple, fast mutex (e.g. it does not
  262. have to be recursive). It is only ever held across very short pieces
  263. of code. Condition variables are only ever signalled/broadcast while
  264. their associated mutex is held. (This constraint simplifies the
  265. implementation of condition variables in certain porting situations.)
  266. For POSIX threads, perl mutexes and condition variables correspond to
  267. POSIX ones.  For FAKE_THREADS, mutexes are stubs and condition variables
  268. are implmented as lists of waiting threads. For FAKE_THREADS, a thread
  269. waits on a condition variable by removing itself from the runnable
  270. list, calling SCHEDULE to change thr to the next appropriate
  271. runnable thread and returning op (i.e. the new threads next op).
  272. This means that fake threads can only block while in PP code.
  273. A PP function which contains a COND_WAIT must be prepared to
  274. handle such restarts and can use the field "private" of struct
  275. thread to record its state. For fake threads, COND_SIGNAL and
  276. COND_BROADCAST work by putting back all the threads on the
  277. condition variables list into the run queue. Note that a mutex
  278. must *not* be held while returning from a PP function.
  279.  
  280. Perl locks and condition variables are both implemented as a
  281. condpair_t structure, containing a mutex, an "owner" condition
  282. variable, an owner thread field and another condition variable).
  283. The structure is attached by 'm' magic to any SV. pp_lock locks
  284. such an object by waiting on the ownercond condition variable until
  285. the owner field is zero and then setting the owner field to its own
  286. thread pointer. The lock is semantically recursive so if the owner
  287. field already matches the current thread then pp_lock returns
  288. straight away. If the owner field has to be filled in then
  289. unlock_condpair is queued as an end-of-block destructor and
  290. that function zeroes out the owner field and signals the ownercond
  291. condition variable, thus waking up any other thread that wants to
  292. lock it. When used as a condition variable, the condpair is locked
  293. (involving the above wait-for-ownership and setting the owner field)
  294. and the spare condition variable field is used for waiting on.
  295.  
  296.  
  297. Thread states
  298.  
  299.  
  300.               $t->join
  301. R_JOINABLE ---------------------> R_JOINED >----\
  302.     |      \  pthread_join(t)         |  ^      |
  303.     |       \                         |  | join | pthread_join
  304.     |        \                        |  |      |
  305.     |         \                       |  \------/
  306.     |          \                      |
  307.     |           \                     |
  308.     |  $t->detach\ pthread_detach     |
  309.     |            _\|                  |
  310. ends|             R_DETACHED     ends | unlink
  311.     |                       \         |
  312.     |                   ends \ unlink |
  313.     |                         \       |
  314.     |                          \      |
  315.     |                           \     |
  316.     |                            \    |
  317.     |                             \   |
  318.     V    join          detach     _\| V
  319. ZOMBIE ----------------------------> DEAD
  320.        pthread_join   pthread_detach
  321.        and unlink     and unlink
  322.  
  323.  
  324.  
  325. Malcolm Beattie
  326. mbeattie@sable.ox.ac.uk
  327. Last updated: 27 November 1997
  328.  
  329. Configure-related info updated 16 July 1998 by
  330. Andy Dougherty <doughera@lafayette.edu>
  331.  
  332. Other minor updates 10 Feb 1999 by
  333. Gurusamy Sarathy
  334.  
  335. More platforms added 26 Jul 1999 by
  336. Jarkko Hietaniemi
  337.