:mod:`_thread` --- Low-level threading API
==========================================

.. module:: _thread
   :synopsis: low-level threading API.


This module provides low-level primitives for managing threads
(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
control sharing their global data space.  For synchronization, simple locks
(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.

Only a subset of CPython's ``_thread`` module is supported, for instance
creation of threads is not supported. 

Constants and functions:


.. data:: LockType

   This is the type of lock objects.


.. function:: exit()

   Raises the :exc:`SystemExit` exception.  When not caught, this will cause the
   thread to exit silently.

.. function:: allocate_lock()

   Return a new lock object.  Methods of locks are described below.  The lock is
   initially unlocked.


.. function:: get_ident()

   Return the 'thread identifier' of the current thread.  This is a nonzero
   integer.  Its value has no direct meaning; it is intended as a magic cookie to
   be used e.g. to index a dictionary of thread-specific data.


.. function:: stack_size([size])

   Not currently supported.

   
Lock objects have the following methods:


.. method:: lock.acquire(waitflag=1, timeout=-1)

   Without any optional argument, this method acquires the lock unconditionally, if
   necessary waiting until it is released by another thread (only one thread at a
   time can acquire a lock --- that's their reason for existence).

   If the integer *waitflag* argument is present, the action depends on its
   value: if it is zero, the lock is only acquired if it can be acquired
   immediately without waiting, while if it is nonzero, the lock is acquired
   unconditionally as above.

   If the floating-point *timeout* argument is present and positive, it
   specifies the maximum wait time in seconds before returning.  A negative
   *timeout* argument specifies an unbounded wait. Unbounded waits are limited
   to 10 minutes at most, at which point :exc:`TimeoutError` will be raised.

   The return value is ``True`` if the lock is acquired successfully,
   ``False`` if not.

   
.. method:: lock.release()

   Releases the lock.  The lock must have been acquired earlier, but not
   necessarily by the same thread.


.. method:: lock.locked()

   Return the status of the lock: ``True`` if it has been acquired by some thread,
   ``False`` if not.

In addition to these methods, lock objects can also be used via the
:keyword:`with` statement. This is the preferred means as Python will 
make sure that the code block is not run unless the lock was
acquired and that it is always released - even if an exception occurs.

Example::

   import _thread

   a_lock = _thread.allocate_lock()

   with a_lock:
       print("a_lock is locked while this executes")