DECLARE_COMPLETION 宏

completion是一种轻量级的机制，它允许一个线程告诉另一个线程工作已经完成。可以利用下面的宏静态创建completion：

DECLARE_COMPLETION(my_completion);

如果运行时创建completion，则必须采用以下方法动态创建和初始化：

struct compltion my_completion;
init_completion(&my_completion);

completion的相关定义包含在kernel/include/linux/completion.h中:

struct completion {
 unsigned int done;
 wait_queue_head_t wait;
};
#define COMPLETION_INITIALIZER(work) 
        { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait) }
#define DECLARE_COMPLETION(work) 
        struct completion work = COMPLETION_INITIALIZER(work)
static inline void init_completion(struct completion *x)
{
    x->done = 0;
    init_waitqueue_head(&x->wait);
}

要等待completion，可进行如下调用：

void wait_for_completion(struct completion *c);

触发completion事件，调用：

void complete(struct completion *c);      //唤醒一个等待线程
void complete_all(struct completion *c); //唤醒所有的等待线程

为说明completion的使用方法，将<<Linux设备驱动程序>>一书中的complete模块的代码摘抄如下：

/*
* complete.c -- the writers awake the readers
*/
------------------------------------------------------------
#include <linux/module.h>
#include <linux/init.h>
#include <linux/sched.h>   /* current and everything */
#include <linux/kernel.h> /* printk() */
#include <linux/fs.h>      /* everything... */
#include <linux/types.h>   /* size_t */
#include <linux/completion.h>
MODULE_LICENSE("Dual BSD/GPL");
static int complete_major = 253; //指定主设备号
DECLARE_COMPLETION(comp);
ssize_t complete_read (
    struct file *filp, char __user *buf,
    size_t       count, loff_t       *pos)
{
    printk(KERN_DEBUG "process %i (%s) going to sleepn",
            current->pid, current->comm);
    wait_for_completion(&comp);
    printk(KERN_DEBUG "awoken %i (%s)n", current->pid, current->comm);
    return 0;
}
ssize_t complete_write (
    struct file *filp, const char __user *buf,
    size_t       count, loff_t            *pos)
{
    printk(KERN_DEBUG "process %i (%s) awakening the readers...n",
            current->pid, current->comm);
    complete(&comp);
    return count;
}
struct file_operations complete_fops = {
    .owner = THIS_MODULE,
    .read = complete_read,
    .write = complete_write,
};
int complete_init(void)
{
    int result;
    result = register_chrdev(complete_major, "completion", &complete_fops);
    if (result < 0)
        return result;
    if (complete_major == 0)
        complete_major = result;
    return 0;
}
void complete_cleanup(void)
{
    unregister_chrdev(complete_major, "completion");
}
module_init(complete_init);
module_exit(complete_cleanup);

该模块定义了一个简单的completion设备：任何试图从该设备中读取的进程都将等待，直到其他设备写入该设备为止。编译此模块的Makefile如下：

obj-m := complete.o
KDIR := /lib/modules/$(shell uname -r)/build
PWD   := $(shell pwd)
default:
    $(MAKE) -C $(KDIR) M=$(PWD) modules
clean:
    rm -f *.ko *.o *.mod.c

在linux终端中执行以下命令，编译生成模块，并进行动态加载

# make
# mknod completion c 253 0
# insmod complete.ko

再打开三个终端，一个用于读进程：

# cat completion

一个用于写进程：

# echo >completion

另一个查看系统日志：

# tail -f /var/log/messages

值得注意的是，当我们使用的complete_all接口时，如果要重复使用一个completion结构，则必须执行 INIT_COMPLETION (struct completion c)来重新初始化它。可以在kernel/include/linux/completion.h中找到这个宏的定义：

#define INIT_COMPLETION(x) ((x).done = 0)

以下代码对书中原有的代码进行了一番变动，将唤醒接口由原来的complete换成了complete_all，并且为了重复利用completion结构，所有读进程都结束后就重新初始化completion结构，具体代码如下：

#include <linux/module.h>
#include <linux/init.h>
#include <linux/sched.h>
#include <linux/kernel.h>
#include <linux/fs.h>
#include <linux/types.h>
#include <linux/completion.h>
MODULE_LICENSE("Dual BSD/GPL");
#undef KERN_DEBUG
#define KERN_DEBUG "<1>"
static int complete_major=253;
static int reader_count = 0;
DECLARE_COMPLETION(comp);
ssize_t complete_read (struct file *filp,char __user *buf,size_t count,loff_t *pos)
{
    printk(KERN_DEBUG "process %i (%s) going to sleep,waiting for writern",current->pid,current->comm);
    reader_count++;
    printk(KERN_DEBUG "In read ,before comletion: reader count = %d n",reader_count);
    wait_for_completion(&comp);
    reader_count--;
    printk(KERN_DEBUG "awoken %s (%i) n",current->comm,current->pid);
    printk(KERN_DEBUG "In read,after completion : reader count = %d n",reader_count);
    /*如果使用complete_all，则completion结构只能用一次，再次使用它时必须调用此宏进行重新初始化*/
    if(reader_count == 0)
        INIT_COMPLETION(comp);
    return 0;
}
ssize_t complete_write(struct file *filp,const char __user *buf,size_t count,loff_t *pos)
{
    printk(KERN_DEBUG "process %i (%s) awoking the readers...n",current->pid,current->comm);
    printk(KERN_DEBUG "In write ,before do complete_all : reader count = %d n",reader_count);
    if(reader_count != 0)
        complete_all(&comp);
    printk(KERN_DEBUG "In write ,after do complete_all : reader count = %d n",reader_count);
    return count;
}
struct file_operations complete_fops={
    .owner = THIS_MODULE,
    .read = complete_read,
    .write = complete_write,
};
int complete_init(void)
{
    int result;
    result=register_chrdev(complete_major,"complete",&complete_fops);
    if(result<0)
        return result;
    if(complete_major==0)
        complete_major =result;
    printk(KERN_DEBUG    "complete driver test init! complete_major=%dn",complete_major);
    printk(KERN_DEBUG "静态初始化completionn");
    return 0;
}
void complete_exit(void)
{
    unregister_chrdev(complete_major,"complete");
    printk(KERN_DEBUG    "complete driver    is removedn");
}
module_init(complete_init);
module_exit(complete_exit);

http://www.21cstar.com/dhome/2007/0824/content_1558.html