← Back to branch summary

~pythonregexp2.7/python/issue2636-11

« back to all changes in this revision

Viewing changes to Doc/library/threading.rst

  • Committer: Jeffrey C. "The TimeHorse" Jacobs
  • Date: 2008-09-21 13:47:31 UTC
  • mfrom: (39021.1.404 Regexp-2.7)
  • mto: This revision was merged to the branch mainline in revision 39030.
  • Revision ID: darklord@timehorse.com-20080921134731-rudomuzeh1b2tz1y
Merged in changes from the latest python source snapshot.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/threading.rst
1
 
 
2
1
:mod:`threading` --- Higher-level threading interface
3
2
=====================================================
4
3
 
13
12
The :mod:`dummy_threading` module is provided for situations where
14
13
:mod:`threading` cannot be used because :mod:`thread` is missing.
15
14
 
 
15
.. note::
 
16
 
 
17
   Starting with Python 2.6, this module provides PEP 8 compliant aliases and
 
18
   properties to replace the ``camelCase`` names that were inspired by Java's
 
19
   threading API. This updated API is compatible with that of the
 
20
   :mod:`multiprocessing` module. However, no schedule has been set for the
 
21
   deprecation of the ``camelCase`` names and they remain fully supported in
 
22
   both Python 2.x and 3.x.
 
23
 
16
24
This module defines the following functions and objects:
17
25
 
18
26
 
19
 
.. function:: activeCount()
 
27
.. function:: active_count()
 
28
              activeCount()
20
29
 
21
30
   Return the number of :class:`Thread` objects currently alive.  The returned
22
31
   count is equal to the length of the list returned by :func:`enumerate`.
30
39
   thread.
31
40
 
32
41
 
33
 
.. function:: currentThread()
 
42
.. function:: current_thread()
 
43
              currentThread()
34
44
 
35
45
   Return the current :class:`Thread` object, corresponding to the caller's thread
36
46
   of control.  If the caller's thread of control was not created through the
40
50
 
41
51
.. function:: enumerate()
42
52
 
43
 
   Return a list of all :class:`Thread` objects currently alive.  The list includes
44
 
   daemonic threads, dummy thread objects created by :func:`currentThread`, and the
45
 
   main thread.  It excludes terminated threads and threads that have not yet been
46
 
   started.
 
53
   Return a list of all :class:`Thread` objects currently alive.  The list
 
54
   includes daemonic threads, dummy thread objects created by
 
55
   :func:`current_thread`, and the main thread.  It excludes terminated threads
 
56
   and threads that have not yet been started.
47
57
 
48
58
 
49
59
.. function:: Event()
395
405
   lock, its caller should.
396
406
 
397
407
 
398
 
.. method:: Condition.notifyAll()
 
408
.. method:: Condition.notify_all()
 
409
            Condition.notifyAll()
399
410
 
400
411
   Wake up all threads waiting on this condition.  This method acts like
401
412
   :meth:`notify`, but wakes up all waiting threads instead of one. If the calling
498
509
   The internal flag is initially false.
499
510
 
500
511
 
501
 
.. method:: Event.isSet()
 
512
.. method:: Event.is_set()
 
513
            Event.isSet()
502
514
 
503
515
   Return true if and only if the internal flag is true.
504
516
 
545
557
 
546
558
Once the thread's activity is started, the thread is considered 'alive'. It
547
559
stops being alive when its :meth:`run` method terminates -- either normally, or
548
 
by raising an unhandled exception.  The :meth:`isAlive` method tests whether the
 
560
by raising an unhandled exception.  The :meth:`is_alive` method tests whether the
549
561
thread is alive.
550
562
 
551
563
Other threads can call a thread's :meth:`join` method.  This blocks the calling
552
564
thread until the thread whose :meth:`join` method is called is terminated.
553
565
 
554
 
A thread has a name.  The name can be passed to the constructor, set with the
555
 
:meth:`setName` method, and retrieved with the :meth:`getName` method.
 
566
A thread has a name.  The name can be passed to the constructor, and read or
 
567
changed through the :attr:`name` attribute.
556
568
 
557
569
A thread can be flagged as a "daemon thread".  The significance of this flag is
558
570
that the entire Python program exits when only daemon threads are left.  The
559
 
initial value is inherited from the creating thread.  The flag can be set with
560
 
the :meth:`setDaemon` method and retrieved with the :meth:`isDaemon` method.
 
571
initial value is inherited from the creating thread.  The flag can be set
 
572
through the :attr:`daemon` attribute.
561
573
 
562
574
There is a "main thread" object; this corresponds to the initial thread of
563
575
control in the Python program.  It is not a daemon thread.
638
650
 
639
651
 
640
652
.. method:: Thread.getName()
641
 
 
642
 
   Return the thread's name.
643
 
 
644
 
 
645
 
.. method:: Thread.setName(name)
646
 
 
647
 
   Set the thread's name.
648
 
 
649
 
   The name is a string used for identification purposes only. It has no semantics.
 
653
            Thread.setName()
 
654
 
 
655
   Old API for :attr:`~Thread.name`.
 
656
 
 
657
 
 
658
.. attribute:: Thread.name
 
659
 
 
660
   A string used for identification purposes only. It has no semantics.
650
661
   Multiple threads may be given the same name.  The initial name is set by the
651
662
   constructor.
652
663
 
653
664
 
654
 
.. method:: Thread.getIdent()
 
665
.. attribute:: Thread.ident
655
666
 
656
 
   Return the 'thread identifier' of this thread or None if the thread has not
657
 
   been started.  This is a nonzero integer.  See the :mod:`thread` module's
658
 
   :func:`get_ident()` function.  Thread identifiers may be recycled when a
659
 
   thread exits and another thread is created.  The identifier is returned
660
 
   even after the thread has exited.
 
667
   The 'thread identifier' of this thread or ``None`` if the thread has not been
 
668
   started.  This is a nonzero integer.  See the :func:`thread.get_ident()`
 
669
   function.  Thread identifiers may be recycled when a thread exits and another
 
670
   thread is created.  The identifier is available even after the thread has
 
671
   exited.
661
672
 
662
673
   .. versionadded:: 2.6
663
674
 
664
675
 
665
 
.. method:: Thread.isAlive()
 
676
.. method:: Thread.is_alive()
 
677
            Thread.isAlive()
666
678
 
667
679
   Return whether the thread is alive.
668
680
 
672
684
 
673
685
 
674
686
.. method:: Thread.isDaemon()
675
 
 
676
 
   Return the thread's daemon flag.
677
 
 
678
 
 
679
 
.. method:: Thread.setDaemon(daemonic)
680
 
 
681
 
   Set the thread's daemon flag to the Boolean value *daemonic*. This must be
682
 
   called before :meth:`start` is called, otherwise :exc:`RuntimeError` is raised.
 
687
            Thread.setDaemon()
 
688
 
 
689
   Old API for :attr:`~Thread.daemon`.
 
690
 
 
691
 
 
692
.. attribute:: Thread.daemon
 
693
 
 
694
   The thread's daemon flag. This must be set before :meth:`start` is called,
 
695
   otherwise :exc:`RuntimeError` is raised.
683
696
 
684
697
   The initial value is inherited from the creating thread.
685
698