1dirq(3) dirq(3)
2
6 dirq - C implementation of the simple directory queue algorithm
7
9 /*
10 * constants
11 */
12 #define DIRQ_VERSION_MAJOR 0
14 #define DIRQ_VERSION_MINOR 5
15 #define DIRQ_VERSION_HEX ((DIRQ_VERSION_MAJOR << 8) | DIRQ_VERSION_MINOR)
16 /*
18 * types
19 */
20 typedef struct dirq_s *dirq_t;
22 typedef int (*dirq_iow)(dirq_t, char *, size_t);
23 typedef int (*dirq_ior)(dirq_t, const char *, size_t);
24 /*
26 * constructors & destructor
27 */
28 dirq_t dirq_new (const char *path);
30 dirq_t dirq_copy (dirq_t dirq);
31 void dirq_free (dirq_t dirq);
32 /*
34 * accessors
35 */
36 void dirq_set_granularity (dirq_t dirq, int value);
38 int dirq_get_granularity (dirq_t dirq);
39 void dirq_set_rndhex (dirq_t dirq, int value);
40 int dirq_get_rndhex (dirq_t dirq);
41 void dirq_set_umask (dirq_t dirq, mode_t value);
42 mode_t dirq_get_umask (dirq_t dirq);
43 void dirq_set_maxlock (dirq_t dirq, int value);
44 int dirq_get_maxlock (dirq_t dirq);
45 void dirq_set_maxtemp (dirq_t dirq, int value);
46 int dirq_get_maxtemp (dirq_t dirq);
47 /*
49 * iterators
50 */
51 const char *dirq_first (dirq_t dirq);
53 const char *dirq_next (dirq_t dirq);
54 /*
56 * main methods
57 */
58 const char *dirq_add (dirq_t dirq, dirq_iow cb);
60 const char *dirq_add_path (dirq_t dirq, const char *path);
61 int dirq_get (dirq_t dirq, const char *name, dirq_ior cb);
62 const char *dirq_get_path (dirq_t dirq, const char *name);
63 int dirq_lock (dirq_t dirq, const char *name, int permissive);
64 int dirq_unlock (dirq_t dirq, const char *name, int permissive);
65 int dirq_remove (dirq_t dirq, const char *name);
66 int dirq_touch (dirq_t dirq, const char *name);
67 int dirq_get_size (dirq_t dirq, const char *name);
68 int dirq_count (dirq_t dirq);
69 int dirq_purge (dirq_t dirq);
70 /*
72 * other methods
73 */
74 void dirq_now (dirq_t dirq, struct timespec *ts);
76 int dirq_get_errcode (dirq_t dirq);
77 const char *dirq_get_errstr (dirq_t dirq);
78 void dirq_clear_error (dirq_t dirq);
79
81 The goal of this library is to offer a "simple" queue system using the
82 underlying filesystem for storage, security and to prevent race
83 conditions via atomic operations. It focuses on simplicity, robustness
84 and scalability.
85 Multiple concurrent readers and writers can interact with the same
87 queue.
88 Other implementations of the same algorithm exist so readers and
90 writers can be written in different programming languages:
91 C: <https://github.com/cern-mig/c-dirq>
93 Java: <https://github.com/cern-mig/java-dirq>
94 Perl: <http://search.cpan.org/dist/Directory-Queue/>
95 Python: <https://github.com/cern-mig/python-dirq>
96 The Perl implementation is the reference one and contains extensive
98 documentation.
99
101 The object oriented API to access the directory queue is implemented
102 with an opaque data type ("dirq_t"), a constructor ("dirq_new") and
103 methods which are C functions requiring the "object" as their first
104 argument. The destructor ("dirq_free") must be called when the object
105 is not needed anymore.
106 The directory queue object is not considered to be thread safe:
108 different threads must use different objects.
109 All the functions that return a string (i.e. "const char *") in fact
111 return a pointer to statically allocated data inside the directory
112 queue object. The caller must use or copy the string before calling
113 other functions since they may override this statically allocated data.
114 Adding and getting elements (i.e. sequences of bytes) is achieved via
116 callback functions working on chunks of bytes so it is never needed to
117 allocate memory holding complete elements.
118 In case of error, the "dirq_get_errcode" and "dirq_get_errstr"
120 functions can be used to get more information. The safest approach is
121 then to stop using the object and free it. However, if needed, the
122 error information can be cleared with "dirq_clear_error".
123
125 dirq_t dirq_new (const char *path)
126 creates a new directory queue object using the given path, setting
127 the internal error information (see "dirq_get_errcode" or
128 "dirq_get_errstr") in case of error
129 dirq_t dirq_copy (dirq_t dirq)
131 creates a new directory queue object which is a copy of the given
132 one
133 void dirq_free (dirq_t dirq)
135 frees the memory associated with the directory queue object
136 void dirq_set_granularity (dirq_t dirq, int value)
138 sets the time granularity for intermediate directories (default:
139 60)
140 int dirq_get_granularity (dirq_t dirq)
142 gets the time granularity for intermediate directories
143 void dirq_set_rndhex (dirq_t dirq, int value)
145 sets the random hexadecimal digit to use in element names (default:
146 randomly generated)
147 int dirq_get_rndhex (dirq_t dirq)
149 gets the random hexadecimal digit to use in element names
150 void dirq_set_umask (dirq_t dirq, mode_t value)
152 sets the umask to use when creating files and directories (default:
153 use the running process' umask)
154 mode_t dirq_get_umask (dirq_t dirq)
156 gets the umask to use when creating files and directories
157 void dirq_set_maxlock (dirq_t dirq, int value)
159 sets the maximum time for a locked element in seconds (default 600)
160 int dirq_get_maxlock (dirq_t dirq)
162 gets the maximum time for a locked element in seconds
163 void dirq_set_maxtemp (dirq_t dirq, int value)
165 sets the maximum time for a temporary element in seconds (default
166 300)
167 int dirq_get_maxtemp (dirq_t dirq)
169 gets the maximum time for a temporary element in seconds
170 const char *dirq_first (dirq_t dirq)
172 returns the first element in the queue, resetting the iterator;
173 returns NULL if the queue is empty or an error occurred
174 const char *dirq_next (dirq_t dirq)
176 returns the next element in the queue, incrementing the iterator;
177 returns NULL if there is no next element or an error occurred
178 const char *dirq_add (dirq_t dirq, dirq_iow cb)
180 adds the given data (via callback) to the queue and returns the
181 corresponding element name or NULL on error
182 const char *dirq_add_path (dirq_t dirq, const char *path)
184 adds the given file (identified by its path) to the queue and
185 returns the corresponding element name or NULL on error, the file
186 must be on the same filesystem and will be moved to the queue
187 int dirq_get (dirq_t dirq, const char *name, dirq_ior cb)
189 gets the data from the given element (which must be locked) via
190 callback; returns 0 on success, -1 on error
191 const char *dirq_get_path (dirq_t dirq, const char *name)
193 gets the file path of the given element (which must be locked),
194 this file can be read but not removed, you must use the remove()
195 method for this; if the given name is NULL, returns the directory
196 queue path itself
197 int dirq_lock (dirq_t dirq, const char *name, int permissive)
199 attempts to lock the given element and returns 0 on success; in
200 case of error, returns 1 (permissive) or -1 (non permissive)
201 int dirq_unlock (dirq_t dirq, const char *name, int permissive)
203 attempts to unlock the given element and returns 0 on success; in
204 case of error, returns 1 (permissive) or -1 (non permissive)
205 int dirq_remove (dirq_t dirq, const char *name)
207 removes the given element (which must be locked) from the queue;
208 returns 0 on success, -1 on error
209 int dirq_touch (dirq_t dirq, const char *name)
211 "touches" the given element (i.e. updates the access and
212 modification times to the current time); returns 0 on success, -1
213 on error
214 int dirq_get_size (dirq_t dirq, const char *name)
216 returns the size (in bytes) of the given element or -1 on error
217 int dirq_count (dirq_t dirq)
219 returns the number of elements in the queue or -1 on error; this
220 also resets the iterator
221 int dirq_purge (dirq_t dirq)
223 purges the queue by removing unused intermediate directories,
224 removing too old temporary elements and unlocking too old locked
225 elements (aka staled locks); this is using the "maxlock" and
226 "maxtemp" attributes of the directory queue object; returns the
227 number of elements purged or -1 on error; this also resets the
228 iterator
229 void dirq_now (dirq_t dirq, struct timespec *ts)
231 returns the current time in the given "timespec" structure
232 int dirq_get_errcode (dirq_t dirq)
234 returns the current error code (usually "errno") or 0 if there is
235 no error
236 const char *dirq_get_errstr (dirq_t dirq)
238 returns the current error string or NULL if there is no error
239 void dirq_clear_error (dirq_t dirq)
241 clears the current error
242
244 Lionel Cons <http://cern.ch/lionel.cons>
245
247 Copyright (C) CERN 2012-2017
248dirq 0.5 2017-08-04 dirq(3)