Lib/multiprocessing/__init__.py

   1 #
   2 # Package analogous to 'threading.py' but using processes
   3 #
   4 # multiprocessing/__init__.py
   5 #
   6 # This package is intended to duplicate the functionality (and much of
   7 # the API) of threading.py but uses processes instead of threads.  A
   8 # subpackage 'multiprocessing.dummy' has the same API but is a simple
   9 # wrapper for 'threading'.
  10 #
  11 # Try calling `multiprocessing.doc.main()` to read the html
  12 # documentation in in a webbrowser.
  13 #
  14 #
  15 # Copyright (c) 2006-2008, R Oudkerk
  16 # All rights reserved.
  17 #
  18 # Redistribution and use in source and binary forms, with or without
  19 # modification, are permitted provided that the following conditions
  20 # are met:
  21 #
  22 # 1. Redistributions of source code must retain the above copyright
  23 #    notice, this list of conditions and the following disclaimer.
  24 # 2. Redistributions in binary form must reproduce the above copyright
  25 #    notice, this list of conditions and the following disclaimer in the
  26 #    documentation and/or other materials provided with the distribution.
  27 # 3. Neither the name of author nor the names of any contributors may be
  28 #    used to endorse or promote products derived from this software
  29 #    without specific prior written permission.
  30 #
  31 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
  32 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  33 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  34 # ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  35 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  36 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  37 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  38 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  39 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  40 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  41 #
  42
  43 __version__ = '0.70a1'
  44
  45 __all__ = [
  46     'Process', 'current_process', 'active_children', 'freeze_support',
  47     'Manager', 'Pipe', 'cpu_count', 'log_to_stderr', 'get_logger',
  48     'allow_connection_pickling', 'BufferTooShort', 'TimeoutError',
  49     'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Condition',
  50     'Event', 'Queue', 'JoinableQueue', 'Pool', 'Value', 'Array',
  51     'RawValue', 'RawArray', 'SUBDEBUG', 'SUBWARNING',
  52     ]
  53
  54 __author__ = 'R. Oudkerk (r.m.oudkerk@gmail.com)'
  55
  56 #
  57 # Imports
  58 #
  59
  60 import os
  61 import sys
  62
  63 from multiprocessing.process import Process, current_process, active_children
  64 from multiprocessing.util import SUBDEBUG, SUBWARNING
  65
  66 #
  67 # Exceptions
  68 #
  69
  70 class ProcessError(Exception):
  71     pass
  72
  73 class BufferTooShort(ProcessError):
  74     pass
  75
  76 class TimeoutError(ProcessError):
  77     pass
  78
  79 class AuthenticationError(ProcessError):
  80     pass
  81
  82 # This is down here because _multiprocessing uses BufferTooShort
  83 import _multiprocessing
  84
  85 #
  86 # Definitions not depending on native semaphores
  87 #
  88
  89 def Manager():
  90     '''
  91     Returns a manager associated with a running server process
  92
  93     The managers methods such as `Lock()`, `Condition()` and `Queue()`
  94     can be used to create shared objects.
  95     '''
  96     from multiprocessing.managers import SyncManager
  97     m = SyncManager()
  98     m.start()
  99     return m
 100
 101 def Pipe(duplex=True):
 102     '''
 103     Returns two connection object connected by a pipe
 104     '''
 105     from multiprocessing.connection import Pipe
 106     return Pipe(duplex)
 107
 108 def cpu_count():
 109     '''
 110     Returns the number of CPUs in the system
 111     '''
 112     if sys.platform == 'win32':
 113         try:
 114             num = int(os.environ['NUMBER_OF_PROCESSORS'])
 115         except (ValueError, KeyError):
 116             num = 0
 117     elif 'bsd' in sys.platform or sys.platform == 'darwin':
 118         try:
 119             num = int(os.popen('sysctl -n hw.ncpu').read())
 120         except ValueError:
 121             num = 0
 122     else:
 123         try:
 124             num = os.sysconf('SC_NPROCESSORS_ONLN')
 125         except (ValueError, OSError, AttributeError):
 126             num = 0
 127
 128     if num >= 1:
 129         return num
 130     else:
 131         raise NotImplementedError('cannot determine number of cpus')
 132
 133 def freeze_support():
 134     '''
 135     Check whether this is a fake forked process in a frozen executable.
 136     If so then run code specified by commandline and exit.
 137     '''
 138     if sys.platform == 'win32' and getattr(sys, 'frozen', False):
 139         from multiprocessing.forking import freeze_support
 140         freeze_support()
 141
 142 def get_logger():
 143     '''
 144     Return package logger -- if it does not already exist then it is created
 145     '''
 146     from multiprocessing.util import get_logger
 147     return get_logger()
 148
 149 def log_to_stderr(level=None):
 150     '''
 151     Turn on logging and add a handler which prints to stderr
 152     '''
 153     from multiprocessing.util import log_to_stderr
 154     return log_to_stderr(level)
 155
 156 def allow_connection_pickling():
 157     '''
 158     Install support for sending connections and sockets between processes
 159     '''
 160     from multiprocessing import reduction
 161
 162 #
 163 # Definitions depending on native semaphores
 164 #
 165
 166 def Lock():
 167     '''
 168     Returns a non-recursive lock object
 169     '''
 170     from multiprocessing.synchronize import Lock
 171     return Lock()
 172
 173 def RLock():
 174     '''
 175     Returns a recursive lock object
 176     '''
 177     from multiprocessing.synchronize import RLock
 178     return RLock()
 179
 180 def Condition(lock=None):
 181     '''
 182     Returns a condition object
 183     '''
 184     from multiprocessing.synchronize import Condition
 185     return Condition(lock)
 186
 187 def Semaphore(value=1):
 188     '''
 189     Returns a semaphore object
 190     '''
 191     from multiprocessing.synchronize import Semaphore
 192     return Semaphore(value)
 193
 194 def BoundedSemaphore(value=1):
 195     '''
 196     Returns a bounded semaphore object
 197     '''
 198     from multiprocessing.synchronize import BoundedSemaphore
 199     return BoundedSemaphore(value)
 200
 201 def Event():
 202     '''
 203     Returns an event object
 204     '''
 205     from multiprocessing.synchronize import Event
 206     return Event()
 207
 208 def Queue(maxsize=0):
 209     '''
 210     Returns a queue object
 211     '''
 212     from multiprocessing.queues import Queue
 213     return Queue(maxsize)
 214
 215 def JoinableQueue(maxsize=0):
 216     '''
 217     Returns a queue object
 218     '''
 219     from multiprocessing.queues import JoinableQueue
 220     return JoinableQueue(maxsize)
 221
 222 def Pool(processes=None, initializer=None, initargs=()):
 223     '''
 224     Returns a process pool object
 225     '''
 226     from multiprocessing.pool import Pool
 227     return Pool(processes, initializer, initargs)
 228
 229 def RawValue(typecode_or_type, *args):
 230     '''
 231     Returns a shared object
 232     '''
 233     from multiprocessing.sharedctypes import RawValue
 234     return RawValue(typecode_or_type, *args)
 235
 236 def RawArray(typecode_or_type, size_or_initializer):
 237     '''
 238     Returns a shared array
 239     '''
 240     from multiprocessing.sharedctypes import RawArray
 241     return RawArray(typecode_or_type, size_or_initializer)
 242
 243 def Value(typecode_or_type, *args, **kwds):
 244     '''
 245     Returns a synchronized shared object
 246     '''
 247     from multiprocessing.sharedctypes import Value
 248     return Value(typecode_or_type, *args, **kwds)
 249
 250 def Array(typecode_or_type, size_or_initializer, **kwds):
 251     '''
 252     Returns a synchronized shared array
 253     '''
 254     from multiprocessing.sharedctypes import Array
 255     return Array(typecode_or_type, size_or_initializer, **kwds)
 256
 257 #
 258 #
 259 #
 260
 261 if sys.platform == 'win32':
 262
 263     def set_executable(executable):
 264         '''
 265         Sets the path to a python.exe or pythonw.exe binary used to run
 266         child processes on Windows instead of sys.executable.
 267         Useful for people embedding Python.
 268         '''
 269         from multiprocessing.forking import set_executable
 270         set_executable(executable)
 271
 272     __all__ += ['set_executable']