← Back to branch summary

~ubuntu-branches/ubuntu/precise/python3.2/precise-proposed

« back to all changes in this revision

Viewing changes to Doc/library/multiprocessing.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2012-03-09 18:40:39 UTC
  • mfrom: (30.1.2 sid)
  • Revision ID: package-import@ubuntu.com-20120309184039-j3yk2emxr1plyo21
Tags: 3.2.3~rc1-1
http://bugs.debian.org/660146
* Python 3.2.3 release candidate 1.
* Update to 20120309 from the 3.2 branch.
* Fix libpython.a symlink. Closes: #660146.
* Build-depend on xauth.
* Run the gdb tests for the debug build only.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/multiprocessing.rst
464
464
For passing messages one can use :func:`Pipe` (for a connection between two
465
465
processes) or a queue (which allows multiple producers and consumers).
466
466
 
467
 
The :class:`Queue` and :class:`JoinableQueue` types are multi-producer,
 
467
The :class:`Queue`, :class:`multiprocessing.queues.SimpleQueue` and :class:`JoinableQueue` types are multi-producer,
468
468
multi-consumer FIFO queues modelled on the :class:`queue.Queue` class in the
469
469
standard library.  They differ in that :class:`Queue` lacks the
470
470
:meth:`~queue.Queue.task_done` and :meth:`~queue.Queue.join` methods introduced
472
472
 
473
473
If you use :class:`JoinableQueue` then you **must** call
474
474
:meth:`JoinableQueue.task_done` for each task removed from the queue or else the
475
 
semaphore used to count the number of unfinished tasks may eventually overflow
 
475
semaphore used to count the number of unfinished tasks may eventually overflow,
476
476
raising an exception.
477
477
 
478
478
Note that one can also create a shared queue by using a manager object -- see
490
490
 
491
491
   If a process is killed using :meth:`Process.terminate` or :func:`os.kill`
492
492
   while it is trying to use a :class:`Queue`, then the data in the queue is
493
 
   likely to become corrupted.  This may cause any other processes to get an
 
493
   likely to become corrupted.  This may cause any other process to get an
494
494
   exception when it tries to use the queue later on.
495
495
 
496
496
.. warning::
552
552
      Return ``True`` if the queue is full, ``False`` otherwise.  Because of
553
553
      multithreading/multiprocessing semantics, this is not reliable.
554
554
 
555
 
   .. method:: put(item[, block[, timeout]])
 
555
   .. method:: put(obj[, block[, timeout]])
556
556
 
557
 
      Put item into the queue.  If the optional argument *block* is ``True``
 
557
      Put obj into the queue.  If the optional argument *block* is ``True``
558
558
      (the default) and *timeout* is ``None`` (the default), block if necessary until
559
559
      a free slot is available.  If *timeout* is a positive number, it blocks at
560
560
      most *timeout* seconds and raises the :exc:`queue.Full` exception if no
563
563
      available, else raise the :exc:`queue.Full` exception (*timeout* is
564
564
      ignored in that case).
565
565
 
566
 
   .. method:: put_nowait(item)
 
566
   .. method:: put_nowait(obj)
567
567
 
568
 
      Equivalent to ``put(item, False)``.
 
568
      Equivalent to ``put(obj, False)``.
569
569
 
570
570
   .. method:: get([block[, timeout]])
571
571
 
610
610
      exits -- see :meth:`join_thread`.
611
611
 
612
612
 
 
613
.. class:: multiprocessing.queues.SimpleQueue()
 
614
 
 
615
   It is a simplified :class:`Queue` type, very close to a locked :class:`Pipe`.
 
616
 
 
617
   .. method:: empty()
 
618
 
 
619
      Return ``True`` if the queue is empty, ``False`` otherwise.
 
620
 
 
621
   .. method:: get()
 
622
 
 
623
      Remove and return an item from the queue.
 
624
 
 
625
   .. method:: put(item)
 
626
 
 
627
      Put *item* into the queue.
 
628
 
 
629
 
613
630
.. class:: JoinableQueue([maxsize])
614
631
 
615
632
   :class:`JoinableQueue`, a :class:`Queue` subclass, is a queue which
692
709
   (By default :data:`sys.executable` is used).  Embedders will probably need to
693
710
   do some thing like ::
694
711
 
695
 
      setExecutable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
 
712
      set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
696
713
 
697
714
   before they can create child processes.  (Windows only)
698
715
 
711
728
Connection objects allow the sending and receiving of picklable objects or
712
729
strings.  They can be thought of as message oriented connected sockets.
713
730
 
714
 
Connection objects usually created using :func:`Pipe` -- see also
 
731
Connection objects are usually created using :func:`Pipe` -- see also
715
732
:ref:`multiprocessing-listeners-clients`.
716
733
 
717
734
.. class:: Connection
727
744
   .. method:: recv()
728
745
 
729
746
      Return an object sent from the other end of the connection using
730
 
      :meth:`send`.  Raises :exc:`EOFError` if there is nothing left to receive
 
747
      :meth:`send`.  Blocks until there its something to receive.  Raises
 
748
      :exc:`EOFError` if there is nothing left to receive
731
749
      and the other end was closed.
732
750
 
733
751
   .. method:: fileno()
734
752
 
735
 
      Returns the file descriptor or handle used by the connection.
 
753
      Return the file descriptor or handle used by the connection.
736
754
 
737
755
   .. method:: close()
738
756
 
756
774
      If *offset* is given then data is read from that position in *buffer*.  If
757
775
      *size* is given then that many bytes will be read from buffer.  Very large
758
776
      buffers (approximately 32 MB+, though it depends on the OS) may raise a
759
 
      ValueError exception
 
777
      :exc:`ValueError` exception
760
778
 
761
779
   .. method:: recv_bytes([maxlength])
762
780
 
763
781
      Return a complete message of byte data sent from the other end of the
764
 
      connection as a string.  Raises :exc:`EOFError` if there is nothing left
 
782
      connection as a string.  Blocks until there is something to receive.
 
783
      Raises :exc:`EOFError` if there is nothing left
765
784
      to receive and the other end has closed.
766
785
 
767
786
      If *maxlength* is specified and the message is longer than *maxlength*
771
790
   .. method:: recv_bytes_into(buffer[, offset])
772
791
 
773
792
      Read into *buffer* a complete message of byte data sent from the other end
774
 
      of the connection and return the number of bytes in the message.  Raises
 
793
      of the connection and return the number of bytes in the message.  Blocks
 
794
      until there is something to receive.  Raises
775
795
      :exc:`EOFError` if there is nothing left to receive and the other end was
776
796
      closed.
777
797
 
873
893
 
874
894
.. note::
875
895
 
876
 
   The :meth:`acquire` method of :class:`BoundedSemaphore`, :class:`Lock`,
877
 
   :class:`RLock` and :class:`Semaphore` has a timeout parameter not supported
878
 
   by the equivalents in :mod:`threading`.  The signature is
879
 
   ``acquire(block=True, timeout=None)`` with keyword parameters being
880
 
   acceptable.  If *block* is ``True`` and *timeout* is not ``None`` then it
881
 
   specifies a timeout in seconds.  If *block* is ``False`` then *timeout* is
882
 
   ignored.
883
 
 
884
896
   On Mac OS X, ``sem_timedwait`` is unsupported, so calling ``acquire()`` with
885
897
   a timeout will emulate that function's behavior using a sleeping loop.
886
898
 
1329
1341
>>>>>>>>>>>>>>>>>>>
1330
1342
 
1331
1343
To create one's own manager, one creates a subclass of :class:`BaseManager` and
1332
 
use the :meth:`~BaseManager.register` classmethod to register new types or
 
1344
uses the :meth:`~BaseManager.register` classmethod to register new types or
1333
1345
callables with the manager class.  For example::
1334
1346
 
1335
1347
   from multiprocessing.managers import BaseManager
1494
1506
      a new shared object -- see documentation for the *method_to_typeid*
1495
1507
      argument of :meth:`BaseManager.register`.
1496
1508
 
1497
 
      If an exception is raised by the call, then then is re-raised by
 
1509
      If an exception is raised by the call, then is re-raised by
1498
1510
      :meth:`_callmethod`.  If some other exception is raised in the manager's
1499
1511
      process then this is converted into a :exc:`RemoteError` exception and is
1500
1512
      raised by :meth:`_callmethod`.
1580
1592
   .. method:: apply(func[, args[, kwds]])
1581
1593
 
1582
1594
      Call *func* with arguments *args* and keyword arguments *kwds*.  It blocks
1583
 
      till the result is ready. Given this blocks, :meth:`apply_async` is better
1584
 
      suited for performing work in parallel. Additionally, the passed in
1585
 
      function is only executed in one of the workers of the pool.
 
1595
      until the result is ready. Given this blocks, :meth:`apply_async` is
 
1596
      better suited for performing work in parallel. Additionally, *func*
 
1597
      is only executed in one of the workers of the pool.
1586
1598
 
1587
1599
   .. method:: apply_async(func[, args[, kwds[, callback[, error_callback]]]])
1588
1600
 
1603
1615
   .. method:: map(func, iterable[, chunksize])
1604
1616
 
1605
1617
      A parallel equivalent of the :func:`map` built-in function (it supports only
1606
 
      one *iterable* argument though).  It blocks till the result is ready.
 
1618
      one *iterable* argument though).  It blocks until the result is ready.
1607
1619
 
1608
1620
      This method chops the iterable into a number of chunks which it submits to
1609
1621
      the process pool as separate tasks.  The (approximate) size of these
1631
1643
 
1632
1644
      The *chunksize* argument is the same as the one used by the :meth:`.map`
1633
1645
      method.  For very long iterables using a large value for *chunksize* can
1634
 
      make make the job complete **much** faster than using the default value of
 
1646
      make the job complete **much** faster than using the default value of
1635
1647
      ``1``.
1636
1648
 
1637
1649
      Also if *chunksize* is ``1`` then the :meth:`!next` method of the iterator
2060
2072
    On Windows many types from :mod:`multiprocessing` need to be picklable so
2061
2073
    that child processes can use them.  However, one should generally avoid
2062
2074
    sending shared objects to other processes using pipes or queues.  Instead
2063
 
    you should arrange the program so that a process which need access to a
 
2075
    you should arrange the program so that a process which needs access to a
2064
2076
    shared resource created elsewhere can inherit it from an ancestor process.
2065
2077
 
2066
2078
Avoid terminating processes
2139
2151
           for i in range(10):
2140
2152
                Process(target=f, args=(lock,)).start()
2141
2153
 
2142
 
Beware replacing sys.stdin with a "file like object"
 
2154
Beware of replacing :data:`sys.stdin` with a "file like object"
2143
2155
 
2144
2156
    :mod:`multiprocessing` originally unconditionally called::
2145
2157
 
2257
2269
 
2258
2270
 
2259
2271
An example showing how to use queues to feed tasks to a collection of worker
2260
 
process and collect the results:
 
2272
processes and collect the results:
2261
2273
 
2262
2274
.. literalinclude:: ../includes/mp_workers.py
2263
2275