http://hi.baidu.com/zhouhanqing/blog/item/1b3cd983f0f468b76d8119fc.html
Python 解释器不是完全线程安全的。当前线程想要安全访问 Python 对象的前提是获取用以支持多线程安全的全局锁。没有锁，甚至多线程程序中最简单的操作都会发生问题。例如，两个线程同时增加一个对象的引用计数，该引用计数可能只增加了一次而非两次。
因此，存在一个规则：只有获得了全局解释器锁的线程才能操作 Python 对象或者调用 Python/C API 函数。为了支持多线程 Python 编程，解释器有规律的释放和回收锁——默认情况下，每100字节指令集循环一次（可以通过sys.setcheckinterval()设置）。类似文件读写之类的 i/o 片也会随锁释放和回收，这样其它的线程在请求 I/O 操作的线程等待I/O操作完成的时候也可以运行。
Python解释器需要为每个独立的线程保留一些薄记信息——为此它使用一个称为PyThreadState的数据结构。然而，这是一个全局变量：当前 PyThreadState 结构的指针。尽管大多数线程包都有办法保存“每线程全局数据”，Python 的内置平台无关线程指令还不支持它。因此，必须明确操作当前的线程状态。
大多数境况下这都是很简单的。全局解释器锁的操作代码主要是以下结构：
1 Save the thread state in a local variable. 2 Release the interpreter lock. 3 ...Do some blocking I/O operation... 4 Reacquire the interpreter lock. 5 Restore the thread state from the local variable.
This is so common that a pair of macros exists to simplify it:
1 Py_BEGIN_ALLOW_THREADS 2 ...Do some blocking I/O operation... 3 Py_END_ALLOW_THREADS
The Py_BEGIN_ALLOW_THREADS macro opens a new block and declares a hidden local variable; the Py_END_ALLOW_THREADS macro closes the block. Another advantage of using these two macros is that when Python is compiled without thread support, they are defined empty, thus saving the thread state and lock manipulations.
Py_BEGIN_ALLOW_THREADS 宏打开一个新的 block 并且定义一个隐藏的局部变量；Py_END_ALLOW_THREADS 宏关闭这个 block 。这两个宏还有一个高级的用途：如果 Python 编译为不支持线程的版本，他们定义为空，因此保存线程状态并锁定操作。
When thread support is enabled, the block above expands to the following code:
1 PyThreadState *_save; 2 3 _save = PyEval_SaveThread(); 4 ...Do some blocking I/O operation... 5 PyEval_RestoreThread(_save);
Using even lower level primitives, we can get roughly the same effect as follows:
1 PyThreadState *_save; 2 3 _save = PyThreadState_Swap(NULL); 4 PyEval_ReleaseLock(); 5 ...Do some blocking I/O operation... 6 PyEval_AcquireLock(); 7 PyThreadState_Swap(_save);
这里有些微妙的不同，细节上，因为锁操作不保证全局变量 erron 的一致，PyEval_RestoreThread() 保存和恢复 errno。同样，不支持线程时，PyEval_SaveThread() 和 PyEval_RestoreThread() 不操作锁，在这种情况下 PyEval_ReleaseLock() 和 PyEval_AcquireLock() 不可用。这使得不支持线程的解释器可以动态加载支持线程的扩展。
全局解释器锁用于保护当前线程状态的指针。当事方锁并保存状态的时候，当前线程状态指针必须在锁释放之前回收（因为另一个指针将会随之获取锁并且在全局变量中保存它自己的线程状态）。相反，获取锁并恢复线程状态的时候，锁必须在保存状态指针之前就获得。
为什么我要对这些进行详细介绍？因为从 C 中创建线程的时候，它们没有全局解释器锁，也没有对应的线程状态数据结构。这些线程在他们使用 Python/C API 之前必须自举，首先要创建线程状态数据结构，然后获取锁，最后保存它们的线程状态指针。完成工作之后，他们可以重置线程状态指针，释放锁，最后释放他们的线程数据结构。
自2.3版开始，线程可以使用 PyGILState_*()函数方便的自动获取以上的所有功能。从C线程中进入 Python 调用的典型方法现在变成：
1 PyGILState_STATE gstate; 2 gstate = PyGILState_Ensure(); 3 4 /* Perform Python actions here. */ 5 result = CallSomeFunction(); 6 /* evaluate result */ 7 8 /* Release the thread. No Python API allowed beyond this point. */ 9 PyGILState_Release(gstate);
注意 PyGILState_*() 函数假定只有一个全局解释器（由 Py_Initialize() 自动创建）。Python 还支持创建附加的解释器（通过 Py_NewInterpreter()），但是 PyGILState_*() 不支持混合多解释器。
1. PyInterpreterState
这个数据结构描述几个协作线程共享的状态。属于同一个解释器的线程共享它们的模块维护和几个其它的内部子项。这个结构没有公开成员。
属于不同解释器的线程除了可用内存、打开的文件描述符之类的进程状态不共享任何东西。全局解释器锁也由所有线程共享，与它们所属的解释器无关。
2. PyThreadState
这个数据结构描述了单个线程的状态。唯一的数据成员是 PyInterpreterState *interp，这个线程的解释器状态。
3. void PyEval_InitThreads( )
初始化和获取全局解释器锁。它应该在主线程中创建，并且应该在第二个线程创建或者类似 PyEval_ReleaseLock() 或 PyEval_ReleaseThread(tstate) 之类的线程操作之前。它不需要在 PyEval_SaveThread() 或 PyEval_RestoreThread()之前调用。
This is a no-op when called for a second time. It is safe to call this function before calling Py_Initialize().
第二次调用没有操作（不做任何事情）。它可以在 Py_Initialize() 被调用之前安全调用。
只有一个主线程的时候，不需要锁操作。这是通常的情景（大多数 Python 程序员不用线程），锁操作稍微拖慢了解释器。因此，锁没有从一开始就创建。这种情况等同于已经获取了锁：只有一个线程的时候，所有的对象访问都是安全的。因此，当该函数初始化锁，它也可以获得锁。Python 线程模块创建一个新的线程之前，它调用PyEval_InitThreads()，了解有锁或者还没有创建锁。当这个调用返回时，它确保锁以被创建，并且调用的线程已经得到它。
It is not safe to call this function when it is unknown which thread (if any) currently has the global interpreter lock.
当前拥有全局解释器锁的线程（或其它什么）未知时，调用这个函数不安全。
This function is not available when thread support is disabled at compile time.
4. int PyEval_ThreadsInitialized( )
如果 PyEval_InitThreads() 已经被调用，这个函数返回非0值。因为单线程的时候可以不调用锁 API，这个函数可以在没有获得锁的情况下使用。这个函数在编译时禁用线程支持的情况下不可用。2.4版新加入。
5. void PyEval_AcquireLock( )
获取全局解释器锁。锁必须提前创建。如果线程已经得到锁，会发生死锁。这个函数在编译时禁用线程支持的情况下不可用。
6. void PyEval_ReleaseLock( )
释放全局解释器锁。锁必须提前创建。这个函数在编译时禁用线程支持的情况下不可用。
7. void PyEval_AcquireThread( PyThreadState *tstate)
获得全局解释器锁并将当前线程状态设定为 tstate ，它不能为NULL。锁必须提前创建。如果线程已经拥有锁，会发生死锁。这个函数在编译时禁用线程支持的情况下不可用。
8. void PyEval_ReleaseThread( PyThreadState *tstate)
重置当前线程状态为NULL并释放全局解释器锁。锁必须提前创建并且以在当前线程中获得。参数 tstate 不能为 NULL。它只能用于校验它描述的当前线程状态——如果它不对，会报告一个致命错误。这个函数在编译时禁用线程支持的情况下不可用。
9. PyThreadState* PyEval_SaveThread( )
释放解释器锁（如果它已经被创建而且定义了线程支持）并且将线程状态设为 NULL ，返回前一个线程状态（如果它不为 NULL ）。如果锁已经创建，当前线程必须获取它。（这个函数甚至在编译时不支持线程的情况下也能使用）。
10. void PyEval_RestoreThread( PyThreadState *tstate)
获取解释器锁（如果支持线程并且锁已经创建）并设置线程状态为非空的 tstate。如果锁已经创建，当前线程必须没有在之前获得它，不然会发生死锁。（这个函数甚至在编译时不支持线程的情况下也能使用）。
The following macros are normally used without a trailing semicolon; look for example usage in the Python source distribution.
以下的宏通常调用的时候不以分号结尾；可以在发布的 Python 源代码中找到使用的示例。
11. Py_BEGIN_ALLOW_THREADS
这个宏展开为 "{ PyThreadState *_save; _save = PyEval_SaveThread();" 。注意它包含一个左大括号；它必须在其后匹配 Py_END_ALLOW_THREADS 宏。这个宏的介绍参见后面。当线程支持在编译时被禁用时它是一个 no-op。
12. Py_END_ALLOW_THREADS
This macro expands to "PyEval_RestoreThread(_save); }". Note that it contains a closing brace; it must be matched with an earlier Py_BEGIN_ALLOW_THREADS macro. See above for further discussion of this macro. It is a no-op when thread support is disabled at compile time.
这个宏展开为 "PyEval_RestoreThread(_save); }" 。注意它包含一个右大括号；它必须在之前匹配一个 Py_BEGIN_ALLOW_THREADS 宏。这个宏的介绍参见前面。当线程支持在编译时被禁用时它是一个 no-op。
13. Py_BLOCK_THREADS
This macro expands to "PyEval_RestoreThread(_save);": it is equivalent to Py_END_ALLOW_THREADS without the closing brace. It is a no-op when thread support is disabled at compile time.
这个宏展开为 "PyEval_RestoreThread(_save);" ；它等同于 Py_END_ALLOW_THREADS 去掉右大括号。当线程支持在编译时被禁用时它是一个 no-op。
14. Py_UNBLOCK_THREADS
This macro expands to "_save = PyEval_SaveThread();": it is equivalent to Py_BEGIN_ALLOW_THREADS without the opening brace and variable declaration. It is a no-op when thread support is disabled at compile time.
这个宏展开为 "_save = PyEval_SaveThread();" ；它是等同于 Py_BEGIN_ALLOW_THREADS 去掉左大括号和变量声明。当线程支持在编译时被禁用时它是一个 no-op。
All of the following functions are only available when thread support is enabled at compile time, and must be called only when the interpreter lock has been created.
以下所有函数只能在编译时确认支持线程的情况下可用，并且必须在解释器锁创建后被调用。
15. PyInterpreterState* PyInterpreterState_New( )
Create a new interpreter state object. The interpreter lock need not be held, but may be held if it is necessary to serialize calls to this function.
创建一个新解释器状态对象。不必要捕获解释器锁，但是当需要同步调用这个函数进行序列化的时候可能需要锁定。
16. void PyInterpreterState_Clear( PyInterpreterState *interp)
Reset all information in an interpreter state object. The interpreter lock must be held.
17. void PyInterpreterState_Delete( PyInterpreterState *interp)
Destroy an interpreter state object. The interpreter lock need not be held. The interpreter state must have been reset with a previous call to PyInterpreterState_Clear().
析构一个解释器状态对象。解释器锁需要获取。解释器对象必须预先用 PyInterpreterState_Clear() 重置。
18. PyThreadState* PyThreadState_New( PyInterpreterState *interp)
Create a new thread state object belonging to the given interpreter object. The interpreter lock need not be held, but may be held if it is necessary to serialize calls to this function.
创建一个从属于给定解释器的新线程状态对象。解释器锁不需要捕获，但是需要同步调用该函数时可能需要捕获。
19. void PyThreadState_Clear( PyThreadState *tstate)
Reset all information in a thread state object. The interpreter lock must be held.
20. void PyThreadState_Delete( PyThreadState *tstate)
Destroy a thread state object. The interpreter lock need not be held. The thread state must have been reset with a previous call to PyThreadState_Clear().
销毁一个线程状态对象。不需要捕获解释器锁。线程状态必须提前调用 PyThreadState_Clear() 进行清除。
21. PyThreadState* PyThreadState_Get( )
Return the current thread state. The interpreter lock must be held. When the current thread state is NULL, this issues a fatal error (so that the caller needn't check for NULL).
返回当前解释器状态。必须捕获解释器锁。当前线程状态如果为 NULL，发生一个致命错误（因此调用者不需要校验NULL）。
22. PyThreadState* PyThreadState_Swap( PyThreadState *tstate)
Swap the current thread state with the thread state given by the argument tstate, which may be NULL. The interpreter lock must be held.
将当前线程状态与给定的参数 tstate 交换，tstate可能为 NULL。解释器锁必须被捕获。
23. PyObject* PyThreadState_GetDict( )
Return value: Borrowed reference.
Return a dictionary in which extensions can store thread-specific state information. Each extension should use a unique key to use to store state in the dictionary. It is okay to call this function when no current thread state is available. If this function returns NULL, no exception has been raised and the caller should assume no current thread state is available. Changed in version 2.3: Previously this could only be called when a current thread is active, and NULL meant that an exception was raised.
返回可存储线程独立的状态信息的一个扩展字典。每个扩展需要一个唯一键用于在字典中保存状态。当前线程状态不可用的时候它也可以调用。如果这个函数返回 NULL，没有抛出异常，调用者会假定当前线程状态无效。自 2.3 版以后的修改：以前它只能在当前线程激活的情况下被调用，如果返回 NULL 就意味着发生了异常。
24. int PyThreadState_SetAsyncExc( long id, PyObject *exc)
Asynchronously raise an exception in a thread. The id argument is the thread id of the target thread; exc is the exception object to be raised. This function does not steal any references to exc. To prevent naive misuse, you must write your own C extension to call this. Must be called with the GIL held. Returns the number of thread states modified; this is normally one, but will be zero if the thread id isn't found. If exc is NULL, the pending exception (if any) for the thread is cleared. This raises no exceptions. New in version 2.3.
在 线程中异步抛出一个异常。参数 id 是目标线程的线程 id ；exc 是要抛出的异常对象。这个函数不获取 exc 的任何引用。为了防止低级错误，你必须自己编写你的 C 扩展来调用它。调用必须捕获 GIL。返回线程状态修改数；通常为 1 ，但是如果线程 id 没有找到就会返回0。如果 exc 是 NULL，所有异常（任何可能）都会从线程中清除。不抛出异常。2.3版新加入。
25. PyGILState_STATE PyGILState_Ensure( )
Ensure that the current thread is ready to call the Python C API regardless of the current state of Python, or of its thread lock. This may be called as many times as desired by a thread as long as each call is matched with a call to PyGILState_Release(). In general, other thread-related APIs may be used between PyGILState_Ensure() and PyGILState_Release() calls as long as the thread state is restored to its previous state before the Release(). For example, normal usage of the Py_BEGIN_ALLOW_THREADS and Py_END_ALLOW_THREADS macros is acceptable.
确 保当前线程已经可以调用与当前 Python 状态无关的 Python C API，或者它的线程锁。当一个线程每次希望匹配到 PyGILState_Release() 调用时可能会反复调用这个函数。通常，在线程状态恢复为 Release() 之前的状态时，其它线程相关的 API 可能会在一对 PyGILState_Ensure() 和 PyGILState_Release() 之间调用。例如，通常可以用于Py_BEGIN_ALLOW_THREADS 宏 Py_END_ALLOW_THREADS。
The return value is an opaque "handle" to the thread state when PyGILState_Acquire() was called, and must be passed to PyGILState_Release() to ensure Python is left in the same state. Even though recursive calls are allowed, these handles cannot be shared - each unique call to PyGILState_Ensure must save the handle for its call to PyGILState_Release.
PyGILState_Acquire ()被调用的时候，返回值是一个不透明的线程状态“句柄”，Python离开当前状态时一定会被被传递到 PyGILState_Release() 。甚至尽管允许递归调用，这些句柄也不能共享——每次调用 PyGILState_Ensure 都是唯一的，它们的句柄对应它们的PyGILState_Release。
When the function returns, the current thread will hold the GIL. Failure is a fatal error. New in version 2.3.
当函数返回，当前线程将会捕获 GIL ，失败会造成致命错误。2.3版新增。
26. void PyGILState_Release( PyGILState_STATE)
Release any resources previously acquired. After this call, Python's state will be the same as it was prior to the corresponding PyGILState_Ensure call (but generally this state will be unknown to the caller, hence the use of the GILState API.)
释放所有之前获取的资源。这个调用之后，Python的状态会与之前 PyGILState_Ensure 调用一致（但是通常这个状态对调用者是未知的，因此使用 GILState API）。
Every call to PyGILState_Ensure() must be matched by a call to PyGILState_Release() on the same thread. New in version 2.3.
每次调用 PyGILState_Ensure() 都要在同一线程对应调用 PyGILState_Release() 。2.3版本新增。
========================================================================
http://blog.csdn.net/liguangyi/archive/2007/06/20/1659697.aspx
一、首先定义一个封装类，主要是保证PyGILState_Ensure, PyGILState_Release配对使用，而且这个类是可以嵌套使用的。
#include <python.h>
class PyThreadStateLock
{
public:
PyThreadStateLock(void)
{
state = PyGILState_Ensure( );
}
~PyThreadStateLock(void)
{
PyGILState_Release( state );
}
private:
PyGILState_STATE state;
};
二、在主线程中，这样处理
// 初始化
Py_Initialize();
// 初始化线程支持
PyEval_InitThreads();
// 启动子线程前执行，为了释放PyEval_InitThreads获得的全局锁，否则子线程可能无法获取到全局锁。
PyEval_ReleaseThread(PyThreadState_Get());
// 其他的处理，如启动子线程等
......
// 保证子线程调用都结束后
PyGILState_Ensure();
Py_Finalize();
// 之后不能再调用任何python的API
三、在主线程，或者子线程中，调用python本身函数的都采用如下处理
{
class PyThreadStateLock PyThreadLock;
// 调用python的API函数处理
......
}
四、另外还有两个和全局锁有关的宏，Py_BEGIN_ALLOW_THREADS 和 Py_END_ALLOW_THREADS。这两个宏是为了在较长时间的C函数调用前，临时释放全局锁，完成后重新获取全局锁，以避免阻塞其他 python的线程继续运行。这两个宏可以这样调用
{
class PyThreadStateLock PyThreadLock;
// 调用python的API函数处理
......
Py_BEGIN_ALLOW_THREADS
// 调用需要长时间的C函数
......
Py_END_ALLOW_THREADS
// 调用python的API函数处理
......
}
========================================================================