pthread clean up

https://www.ibm.com/developerworks/cn/linux/thread/posix_threadapi/part4/

http://www.cnblogs.com/xfiver/archive/2013/01/23/2873725.html

线程终止方式

一般来说，Posix的线程终止有两种情况：正常终止和非正常终止。线程主动调用pthread_exit()或者从线程函数中return都将使线程正常退出，这是可预见的退出方式；非正常终止是线程在其他线程的干预下，或者由于自身运行出错（比如访问非法地址）而退出，这种退出方式是不可预见的。

---

回页首

线程终止时的清理

不论是可预见的线程终止还是异常终止，都会存在资源释放的问题，在不考虑因运行出错而退出的前提下，如何保证线程终止时能顺利的释放掉自己所占用的资源，特别是锁资源，就是一个必须考虑解决的问题。

最经常出现的情形是资源独占锁的使用：线程为了访问临界资源而为其加上锁，但在访问过程中被外界取消，如果线程处于响应取消状态，且采用异步方式响应，或者在打开独占锁以前的运行路径上存在取消点，则该临界资源将永远处于锁定状态得不到释放。外界取消操作是不可预见的，因此的确需要一个机制来简化用于资源释放的编程。

在POSIX线程API中提供了一个pthread_cleanup_push()/pthread_cleanup_pop()函数对用于自动释放资源--从pthread_cleanup_push()的调用点到pthread_cleanup_pop()之间的程序段中的终止动作（包括调用pthread_exit()和取消点终止）都将执行pthread_cleanup_push()所指定的清理函数。API定义如下：

void pthread_cleanup_push(void (*routine) (void  *),  void *arg)
void pthread_cleanup_pop(int execute)

pthread_cleanup_push()/pthread_cleanup_pop()采用先入后出的栈结构管理，void routine(void *arg)函数在调用pthread_cleanup_push()时压入清理函数栈，多次对pthread_cleanup_push()的调用将在清理函数栈中形成一个函数链，在执行该函数链时按照压栈的相反顺序弹出。

execute参数表示执行到pthread_cleanup_pop()时是否在弹出清理函数的同时执行该函数，为0表示不执行，非0为执行；这个参数并不影响异常终止时清理函数的执行。

补充说明：

. 线程创建

pthread_create()函数返回值0，表示创建成功，线程id保存载tidp中；失败则返回非零，需自行处理，不会修改errno值

. 线程终止

a. 任一线程调用exit, _Exit, _exit都将导致整个进程终止；

b. 单个线程退出方式有三种：

　　> 线程执行函数start_rtn()中使用return返回，返回值为线程退出码；

　　> 被同一个进程的其他线程使用pthread_cancel()取消；

　　> 线程自身调用了pthread_exit()；

说明：pthread_join(pthread_t tid, void **rval_ptr)函数会阻塞调用线程，直到tid线程通过上述三种方式终止退出，且return/pthread_exit()方式会设置相应线程退出码rval_ptr，而pthread_cancel()取消的线程，将退出码设置为PTHREAD_CANCELED.

. 线程清理处理程序（thread cleanup handler）

.a> pthread_cleanup_push()与pthread_cleanup_pop()均为<pthread.h>中实现的宏定义，具体实现如下：

?
pthread_cleanup_push and pthread_cleanup_pop are macros and must always
   be used in matching pairs at the same nesting level of braces.  */
#  define pthread_cleanup_push(routine, arg) \
  do {                                        \
    __pthread_cleanup_class __clframe (routine, arg) 

/* Remove a cleanup handler installed by the matching pthread_cleanup_push.
   If EXECUTE is non-zero, the handler function is called. */
#  define pthread_cleanup_pop(execute) \
    __clframe.__setdoit (execute);                        \
  } while ()
 可见push/pop中的{/}是一一对应的，因此pthread_cleanup_push/pop()也应一一对应出现，否则编译出错。

.b> 当线程执行下列之一操作时调用清理函数，thread_cleanup_push由栈结构实现，注意清理程序调用的顺序，先入后出。

　　: 调用pthread_exit()时，而直接return不会出发清理函数；

　　: 相应取消请求pthread_cancel()时；

　　: 使用非零execute参数调用pthread_cleanup_pop()时；

尤其需注意pthread_cleanup_pop()参数不同及此语句所处位置不同而有不同效果。

看此代码实例，注意return或pthread_exit()位置不同导致pthread_cleanup_pop()不同参数的效果变化。

include <pthread.h>
void testPointerSize()
{
    void *tret;
    printf("size of pointer in x86-64：%d\n",sizeof(tret));
    //result is 8 in x86-64.
    //which is 4 in x86-32. 

    printf("size of int in x86-64：%d\n",sizeof(int));
    //result is 4 in x86-64.
    //which is also 4 in x86-32.
}
void cleanup(void *arg)
{
    printf("cleanup:%s\n",(char *)arg);
}
void * thr_fn1(void *arg)
{
    printf("thread 1 start\n");
    pthread_cleanup_push(cleanup, "thread 1 first handler");
    pthread_cleanup_push(cleanup, "thread 1 second handler");
    if(arg)
        return ((void *));//arg !=0 ,return here.
//  return here will not triger any cleanup.
    pthread_cleanup_pop();
    pthread_cleanup_pop();
    return ((void *));//will not run this
}
void * thr_fn2(void *arg)
{
    printf("thread 2 start\n");
    pthread_cleanup_push(cleanup, "thread 2 first handler");
    pthread_cleanup_push(cleanup, "thread 2 second handler");
    pthread_cleanup_pop();
    pthread_cleanup_pop();
    return ((void *));
//  return here can triger cleanup second handler;
} 

void * thr_fn3(void *arg)
{
    printf("thread 3 start\n");
    pthread_cleanup_push(cleanup, "thread 3 first handler");
    pthread_cleanup_push(cleanup, "thread 3 second handler");
    if(arg)
        pthread_exit((void *));
    //pthread_exit() here will triger both cleanup first&second handler.
    pthread_cleanup_pop();
    pthread_cleanup_pop();
    pthread_exit((void *));//wont run this
}
void * thr_fn4(void *arg)
{
    printf("thread 4 start\n");
    pthread_cleanup_push(cleanup, "thread 4 first handler");
    pthread_cleanup_push(cleanup, "thread 4 second handler");
    pthread_cleanup_pop();
    pthread_cleanup_pop();
    pthread_exit((void *));
    //pthread_exit() here will triger cleanup second handler.
} 

int main(void)
{
    testPointerSize();
    int err;
    pthread_t tid1, tid2, tid3, tid4;
    void *tret; 

    err = pthread_create(&tid1, NULL, thr_fn1, (void *));
    err = pthread_join(tid1,&tret);
    printf("thread 1 exit code %d\n",(int)tret); 

    err = pthread_create(&tid2, NULL, thr_fn2, (void *));
    err = pthread_join(tid2, &tret);
    printf("thread 2 exit code %d\n",(int)tret); 

    err = pthread_create(&tid3, NULL, thr_fn3, (void *));
    err = pthread_join(tid3,&tret);
    printf("thread 3 exit code %d\n",(int)tret); 

    err = pthread_create(&tid4, NULL, thr_fn4, (void *));
    err = pthread_join(tid4, &tret);
    printf("thread 4 exit code %d\n",(int)tret);
} 

运行结果：

?
[root@hello testData]# ./test
size of pointer in x86-：
size of int in x86-：
thread  start
thread  exit code
thread  start
cleanup:thread  first handler
thread  exit code
thread  start
cleanup:thread  second handler
cleanup:thread  first handler
thread  exit code
thread  start
cleanup:thread  second handler
thread  exit code  

由上述测试程序总结如下：

1> push与pop间的return，将导致清理程序不被触发；

2> 位于pop之后return，由pop的参数确定是否触发清理程序，非零参数触发，零参数不触发；

3> push/pop间的pthread_exit()，将触发所有清理函数；

4>位于pop之后的pthread_exit()时，pop参数决定是否触发清理程序；

其实，上述四种情况只是测试验证了前文3.b所说三个条件，加深理解。

参考文献：

1. Posix线程编程指南(4)

2. <UNIX环境高级编程（第2版）> P295-296程序

3. pthread_cleanup_push()/pthread_cleanup_pop()的详解

4. Linux中vim的列编辑实例 （Mark记录）

pthread_cleanup_push()/pthread_cleanup_pop()是以宏方式实现的，这是pthread.h中的宏定义：

#define pthread_cleanup_push(routine,arg)                                     \
  { struct _pthread_cleanup_buffer _buffer;                                   \
    _pthread_cleanup_push (&_buffer, (routine), (arg));
#define pthread_cleanup_pop(execute)                                          \
    _pthread_cleanup_pop (&_buffer, (execute)); }

可见，pthread_cleanup_push()带有一个"{"，而pthread_cleanup_pop()带有一个"}"，因此这两个函数必须成对出现，且必须位于程序的同一级别的代码段中才能通过编译。在下面的例子里，当线程在"do some work"中终止时，将主动调用pthread_mutex_unlock(mut)，以完成解锁动作。

pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
pthread_mutex_lock(&mut);
/* do some work */
pthread_mutex_unlock(&mut);
pthread_cleanup_pop(0);

必须要注意的是，如果线程处于PTHREAD_CANCEL_ASYNCHRONOUS状态，上述代码段就有可能出错，因为CANCEL事件有可能在pthread_cleanup_push()和pthread_mutex_lock()之间发生，或者在pthread_mutex_unlock()和pthread_cleanup_pop()之间发生，从而导致清理函数unlock一个并没有加锁的mutex变量，造成错误。因此，在使用清理函数的时候，都应该暂时设置成PTHREAD_CANCEL_DEFERRED模式。为此，POSIX的Linux实现中还提供了一对不保证可移植的pthread_cleanup_push_defer_np()/pthread_cleanup_pop_defer_np()扩展函数，功能与以下代码段相当：

{ int oldtype;
 pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
 pthread_cleanup_push(routine, arg);
 ...
 pthread_cleanup_pop(execute);
 pthread_setcanceltype(oldtype, NULL);
 }