[PATCH] Numerous fixes to kernel-doc info in source files.
[linux-2.6.git] / kernel / kthread.c
1 /* Kernel thread helper functions.
2  *   Copyright (C) 2004 IBM Corporation, Rusty Russell.
3  *
4  * Creation is done via keventd, so that we get a clean environment
5  * even if we're invoked from userspace (think modprobe, hotplug cpu,
6  * etc.).
7  */
8 #include <linux/sched.h>
9 #include <linux/kthread.h>
10 #include <linux/completion.h>
11 #include <linux/err.h>
12 #include <linux/unistd.h>
13 #include <linux/file.h>
14 #include <linux/module.h>
15 #include <linux/mutex.h>
16 #include <asm/semaphore.h>
17
18 /*
19  * We dont want to execute off keventd since it might
20  * hold a semaphore our callers hold too:
21  */
22 static struct workqueue_struct *helper_wq;
23
24 struct kthread_create_info
25 {
26         /* Information passed to kthread() from keventd. */
27         int (*threadfn)(void *data);
28         void *data;
29         struct completion started;
30
31         /* Result passed back to kthread_create() from keventd. */
32         struct task_struct *result;
33         struct completion done;
34
35         struct work_struct work;
36 };
37
38 struct kthread_stop_info
39 {
40         struct task_struct *k;
41         int err;
42         struct completion done;
43 };
44
45 /* Thread stopping is done by setthing this var: lock serializes
46  * multiple kthread_stop calls. */
47 static DEFINE_MUTEX(kthread_stop_lock);
48 static struct kthread_stop_info kthread_stop_info;
49
50 /**
51  * kthread_should_stop - should this kthread return now?
52  *
53  * When someone calls kthread_stop() on your kthread, it will be woken
54  * and this will return true.  You should then return, and your return
55  * value will be passed through to kthread_stop().
56  */
57 int kthread_should_stop(void)
58 {
59         return (kthread_stop_info.k == current);
60 }
61 EXPORT_SYMBOL(kthread_should_stop);
62
63 static void kthread_exit_files(void)
64 {
65         struct fs_struct *fs;
66         struct task_struct *tsk = current;
67
68         exit_fs(tsk);           /* current->fs->count--; */
69         fs = init_task.fs;
70         tsk->fs = fs;
71         atomic_inc(&fs->count);
72         exit_files(tsk);
73         current->files = init_task.files;
74         atomic_inc(&tsk->files->count);
75 }
76
77 static int kthread(void *_create)
78 {
79         struct kthread_create_info *create = _create;
80         int (*threadfn)(void *data);
81         void *data;
82         sigset_t blocked;
83         int ret = -EINTR;
84
85         kthread_exit_files();
86
87         /* Copy data: it's on keventd's stack */
88         threadfn = create->threadfn;
89         data = create->data;
90
91         /* Block and flush all signals (in case we're not from keventd). */
92         sigfillset(&blocked);
93         sigprocmask(SIG_BLOCK, &blocked, NULL);
94         flush_signals(current);
95
96         /* By default we can run anywhere, unlike keventd. */
97         set_cpus_allowed(current, CPU_MASK_ALL);
98
99         /* OK, tell user we're spawned, wait for stop or wakeup */
100         __set_current_state(TASK_INTERRUPTIBLE);
101         complete(&create->started);
102         schedule();
103
104         if (!kthread_should_stop())
105                 ret = threadfn(data);
106
107         /* It might have exited on its own, w/o kthread_stop.  Check. */
108         if (kthread_should_stop()) {
109                 kthread_stop_info.err = ret;
110                 complete(&kthread_stop_info.done);
111         }
112         return 0;
113 }
114
115 /* We are keventd: create a thread. */
116 static void keventd_create_kthread(struct work_struct *work)
117 {
118         struct kthread_create_info *create =
119                 container_of(work, struct kthread_create_info, work);
120         int pid;
121
122         /* We want our own signal handler (we take no signals by default). */
123         pid = kernel_thread(kthread, create, CLONE_FS | CLONE_FILES | SIGCHLD);
124         if (pid < 0) {
125                 create->result = ERR_PTR(pid);
126         } else {
127                 wait_for_completion(&create->started);
128                 read_lock(&tasklist_lock);
129                 create->result = find_task_by_pid(pid);
130                 read_unlock(&tasklist_lock);
131         }
132         complete(&create->done);
133 }
134
135 /**
136  * kthread_create - create a kthread.
137  * @threadfn: the function to run until signal_pending(current).
138  * @data: data ptr for @threadfn.
139  * @namefmt: printf-style name for the thread.
140  *
141  * Description: This helper function creates and names a kernel
142  * thread.  The thread will be stopped: use wake_up_process() to start
143  * it.  See also kthread_run(), kthread_create_on_cpu().
144  *
145  * When woken, the thread will run @threadfn() with @data as its
146  * argument. @threadfn() can either call do_exit() directly if it is a
147  * standalone thread for which noone will call kthread_stop(), or
148  * return when 'kthread_should_stop()' is true (which means
149  * kthread_stop() has been called).  The return value should be zero
150  * or a negative error number; it will be passed to kthread_stop().
151  *
152  * Returns a task_struct or ERR_PTR(-ENOMEM).
153  */
154 struct task_struct *kthread_create(int (*threadfn)(void *data),
155                                    void *data,
156                                    const char namefmt[],
157                                    ...)
158 {
159         struct kthread_create_info create;
160
161         create.threadfn = threadfn;
162         create.data = data;
163         init_completion(&create.started);
164         init_completion(&create.done);
165         INIT_WORK(&create.work, keventd_create_kthread);
166
167         /*
168          * The workqueue needs to start up first:
169          */
170         if (!helper_wq)
171                 create.work.func(&create.work);
172         else {
173                 queue_work(helper_wq, &create.work);
174                 wait_for_completion(&create.done);
175         }
176         if (!IS_ERR(create.result)) {
177                 va_list args;
178                 va_start(args, namefmt);
179                 vsnprintf(create.result->comm, sizeof(create.result->comm),
180                           namefmt, args);
181                 va_end(args);
182         }
183
184         return create.result;
185 }
186 EXPORT_SYMBOL(kthread_create);
187
188 /**
189  * kthread_bind - bind a just-created kthread to a cpu.
190  * @k: thread created by kthread_create().
191  * @cpu: cpu (might not be online, must be possible) for @k to run on.
192  *
193  * Description: This function is equivalent to set_cpus_allowed(),
194  * except that @cpu doesn't need to be online, and the thread must be
195  * stopped (i.e., just returned from kthread_create()).
196  */
197 void kthread_bind(struct task_struct *k, unsigned int cpu)
198 {
199         BUG_ON(k->state != TASK_INTERRUPTIBLE);
200         /* Must have done schedule() in kthread() before we set_task_cpu */
201         wait_task_inactive(k);
202         set_task_cpu(k, cpu);
203         k->cpus_allowed = cpumask_of_cpu(cpu);
204 }
205 EXPORT_SYMBOL(kthread_bind);
206
207 /**
208  * kthread_stop - stop a thread created by kthread_create().
209  * @k: thread created by kthread_create().
210  *
211  * Sets kthread_should_stop() for @k to return true, wakes it, and
212  * waits for it to exit.  Your threadfn() must not call do_exit()
213  * itself if you use this function!  This can also be called after
214  * kthread_create() instead of calling wake_up_process(): the thread
215  * will exit without calling threadfn().
216  *
217  * Returns the result of threadfn(), or %-EINTR if wake_up_process()
218  * was never called.
219  */
220 int kthread_stop(struct task_struct *k)
221 {
222         int ret;
223
224         mutex_lock(&kthread_stop_lock);
225
226         /* It could exit after stop_info.k set, but before wake_up_process. */
227         get_task_struct(k);
228
229         /* Must init completion *before* thread sees kthread_stop_info.k */
230         init_completion(&kthread_stop_info.done);
231         smp_wmb();
232
233         /* Now set kthread_should_stop() to true, and wake it up. */
234         kthread_stop_info.k = k;
235         wake_up_process(k);
236         put_task_struct(k);
237
238         /* Once it dies, reset stop ptr, gather result and we're done. */
239         wait_for_completion(&kthread_stop_info.done);
240         kthread_stop_info.k = NULL;
241         ret = kthread_stop_info.err;
242         mutex_unlock(&kthread_stop_lock);
243
244         return ret;
245 }
246 EXPORT_SYMBOL(kthread_stop);
247
248 static __init int helper_init(void)
249 {
250         helper_wq = create_singlethread_workqueue("kthread");
251         BUG_ON(!helper_wq);
252
253         return 0;
254 }
255
256 core_initcall(helper_init);