xref: /unit/src/nxt_job.h (revision 20:4dc92b438f58)
1 
2 /*
3  * Copyright (C) Igor Sysoev
4  * Copyright (C) NGINX, Inc.
5  */
6 
7 #ifndef _NXT_JOB_H_INCLUDED_
8 #define _NXT_JOB_H_INCLUDED_
9 
10 
11 /*
12  * A job may run by separate thread, so each job should have its
13  * its own mem_pool.  A job itself is allocated from this mem_pool.
14  * On job completion a job initiator can destroy the job at once
15  * with nxt_job_destroy() or can postpone the destruction with
16  * nxt_job_cleanup_add(), if the initiator uses data from the job's
17  * mem_pool.
18  *
19  * Several child jobs may run in context of another job in the same
20  * thread.  In this case the child job may use a mem_pool of the
21  * parent job and the child job is allocated using the mem_pool's cache.
22  * nxt_job_destroy() just returns the job to the cache.  All job
23  * allocations however still remain in the parent mem_pool.
24  *
25  * The first thread in job thread pool is created on demand.  If this
26  * operation fails the job abort handler is called.  It also is called
27  * if the job is canceled.  To avoid race condition the abort handler
28  * always runs in context of a thread initiated the job.  The abort
29  * handler may be as simple as nxt_job_destroy().
30  */
31 
32 
33 typedef struct {
34     void                *data;
35 
36     nxt_task_t          *task;
37 
38     nxt_work_handler_t  abort_handler;
39 
40     uint16_t            cache_size;
41     uint8_t             cancel;          /* 1 bit */
42 
43     nxt_mem_pool_t      *mem_pool;
44     nxt_queue_link_t    link;
45 
46 #if (NXT_THREADS)
47     nxt_thread_pool_t   *thread_pool;
48     nxt_event_engine_t  *engine;
49     nxt_log_t           *log;
50 #endif
51 
52     nxt_work_t          work;
53 
54 #if (NXT_DEBUG)
55     const char          *name;
56 #endif
57 
58 } nxt_job_t;
59 
60 
61 NXT_EXPORT void *nxt_job_create(nxt_mem_pool_t *mp, size_t size);
62 NXT_EXPORT void nxt_job_init(nxt_job_t *job, size_t size);
63 NXT_EXPORT void nxt_job_destroy(nxt_task_t *task, void *data);
64 NXT_EXPORT nxt_int_t nxt_job_cleanup_add(nxt_mem_pool_t *mp, nxt_job_t *job);
65 
66 NXT_EXPORT void nxt_job_start(nxt_task_t *task, nxt_job_t *job,
67     nxt_work_handler_t handler);
68 NXT_EXPORT void nxt_job_return(nxt_task_t *task, nxt_job_t *job,
69     nxt_work_handler_t handler);
70 
71 
72 #define                                                                       \
73 nxt_job_cancel(job)                                                           \
74     (job)->cancel = 1
75 
76 
77 #if (NXT_DEBUG)
78 
79 #define                                                                       \
80 nxt_job_set_name(job, text)                                                   \
81     (job)->name = text
82 
83 #else
84 
85 #define                                                                       \
86 nxt_job_set_name(job, text)
87 
88 #endif
89 
90 
91 #endif /* _NXT_JOB_H_INCLUDED_ */
92