~ubuntu-branches/ubuntu/quantal/globus-gass-cache/quantal
» Revision
7
: .pc/globus-gass-cache.patch/globus_gass_cache.h
« back to all changes in this revision
Viewing changes to .pc/globus-gass-cache.patch/globus_gass_cache.h
- browse files at revision 7
- compare with another revision
- download diff
- download tarball
- view history from revision 7
- Committer: Package Import Robot
- Author(s): Mattias Ellert
- Date: 2012-01-24 22:53:19 UTC
- mfrom: (5.1.2 sid)
- Revision ID: package-import@ubuntu.com-20120124225319-o7jmdf1azowro30c
Tags: 8.1-2
Fix broken links in README file
- files added:
- GLOBUS_LICENSE
- files removed:
- .pc
- .pc/globus-gass-cache.patch
- debian/patches
- files modified:
- Makefile.am
added
removed
.pc/globus-gass-cache.patch/globus_gass_cache.h
1
/*
2
* Copyright 1999-2006 University of Chicago
3
*
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
7
*
8
* http://www.apache.org/licenses/LICENSE-2.0
9
*
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
15
*/
16
17
/******************************************************************************
18
globus_gass_cache.h
19
20
Description:
21
Header of the GASS CACHE MANAGEMENT API.
22
23
CVS Information:
24
25
$Source: /home/globdev/CVS/globus-packages/gass/cache/source/globus_gass_cache.h,v $
26
$Date: 2006/01/19 05:54:34 $
27
$Revision: 1.22 $
28
29
******************************************************************************/
30
#ifndef _GLOBUS_GASS_INCLUDE_GLOBUS_GASS_CACHE_H_
31
#define _GLOBUS_GASS_INCLUDE_GLOBUS_GASS_CACHE_H_
32
33
#ifndef EXTERN_C_BEGIN
34
#ifdef __cplusplus
35
#define EXTERN_C_BEGIN extern "C" {
36
#define EXTERN_C_END }
37
#else
38
#define EXTERN_C_BEGIN
39
#define EXTERN_C_END
40
#endif
41
#endif
42
43
#include <sys/param.h>
44
45
#include "globus_common.h"
46
47
EXTERN_C_BEGIN
48
49
50
/*
51
* Codes returned by globus_gass_cache module
52
*/
53
54
#define GLOBUS_GASS_CACHE_ADD_NEW 1
55
#define GLOBUS_GASS_CACHE_URL_NOT_FOUND 2
56
#define GLOBUS_GASS_CACHE_ADD_EXISTS 3
57
58
#define GLOBUS_GASS_CACHE_ERROR_NO_HOME -1
59
#define GLOBUS_GASS_CACHE_ERROR_CAN_NOT_CREATE -2
60
#define GLOBUS_GASS_CACHE_ERROR_NAME_TOO_LONG -3
61
#define GLOBUS_GASS_CACHE_ERROR_LOCK_ERROR -4
62
/* not used in a first impl.: */
63
#define GLOBUS_GASS_CACHE_ERROR_LOCK_TIME_OUT -5
64
#define GLOBUS_GASS_CACHE_ERROR_OPEN_STATE -6
65
#define GLOBUS_GASS_CACHE_ERROR_STATE_F_CORRUPT -7
66
#define GLOBUS_GASS_CACHE_ERROR_NO_MEMORY -8
67
#define GLOBUS_GASS_CACHE_ERROR_CAN_NOT_CREATE_DATA_F -9
68
/* only for "done" or delete :*/
69
#define GLOBUS_GASS_CACHE_ERROR_URL_NOT_FOUND -10
70
#define GLOBUS_GASS_CACHE_ERROR_CAN_NOT_DEL_LOCK -11
71
#define GLOBUS_GASS_CACHE_ERROR_WRONG_TAG -12
72
#define GLOBUS_GASS_CACHE_ERROR_ALREADY_DONE -13
73
#define GLOBUS_GASS_CACHE_ERROR_CAN_NOT_WRITE -14
74
#define GLOBUS_GASS_CACHE_ERROR_CAN_NOT_READ -15
75
#define GLOBUS_GASS_CACHE_ERROR_CAN_NOT_DELETE_DATA_F -16
76
#define GLOBUS_GASS_CACHE_ERROR_CACHE_NOT_OPENED -17
77
#define GLOBUS_GASS_CACHE_ERROR_CACHE_ALREADY_OPENED -18
78
#define GLOBUS_GASS_CACHE_ERROR_INVALID_PARRAMETER -19
79
#define GLOBUS_GASS_CACHE_ERROR_INVALID_VERSION -20
80
#define GLOBUS_GASS_CACHE_ERROR_NO_SPACE -21
81
#define GLOBUS_GASS_CACHE_ERROR_QUOTA_EXCEEDED -22
82
83
#define GLOBUS_GASS_CACHE_TIMESTAMP_UNKNOWN 0UL
84
85
#if !defined(PATH_MAX) && defined(MAXPATHLEN)
86
# define PATH_MAX MAXPATHLEN
87
#endif
88
89
/*
90
* Other definitions
91
*/
92
93
94
/*
95
* Structure: globus_gass_cache_t
96
*
97
* Data structure used to store informations concerning an open cache
98
* directory. This structure MUST NOT be modified directly, but passed to
99
* the globus_gass_cache functions
100
*/
101
typedef struct globus_i_gass_cache_t * globus_gass_cache_t;
102
103
104
/*
105
*
106
* FUNCTIONS
107
*
108
*/
109
110
/*
111
* globus_gass_cache_open()
112
*
113
* Open the cache specified by the cache_directory_path argument, and return
114
* a cache handle that can be used in subsequent cache calls.
115
*
116
* If cache_directory_path is NULL, then use the value contained in the
117
* GLOBUS_GASS_CACHE_DEFAULT environment variable if it is defined,
118
* otherwise use ~/.globus_gass_cache.
119
*
120
* The cache_directory_path must be a directory. If it is a file, this call
121
* will fail with a non-0 return value.
122
*
123
* If the specified directory does not exist, then this call will create the
124
* directory.
125
*
126
* Parameters:
127
*
128
* cache_directory_path : Path to the cache directory to open.
129
* Can be NULL (see above)
130
*
131
* cache_handle->is_init: checked and return an error if
132
* cache_handle has already been used.
133
*
134
* cache_handle: Structure containning all the necessary
135
* information to access the cache (file names, descriptor,...)
136
* (see globus_gass_gache.h) Some files are also opened:
137
* globus_gass_cache_close() must be called subsequently to close those
138
* files.
139
* This parameter is modified by the globus_gass_cache_open()
140
*
141
* Returns:
142
* BLOBUS_SUCCESS or error code:
143
* GLOBUS_GASS_CACHE_ERROR_CACHE_ALREADY_OPENED
144
* GLOBUS_GASS_CACHE_ERROR_NAME_TOO_LONG if the cache directory path is
145
* too long
146
* GLOBUS_GASS_CACHE_ERROR_NO_HOME if cache_directory_path is NULL and
147
* the env. variable GLOBUS_GASS_CACHE_DEFAULT is empty and
148
* the env. variable $HOME is not defined !
149
* GLOBUS_GASS_CACHE_ERROR_CAN_NOT_CREATE if the cache directory or any
150
* necessary file can not be created.
151
*
152
*/
153
extern
154
int
155
globus_gass_cache_open(const char* cache_directory_path,
156
globus_gass_cache_t* cache_handle);
157
158
159
/*
160
* globus_gass_cache_close()
161
*
162
*
163
* Close (NOT delete) a previously opened cache:
164
* - close the opened files and
165
* - free the memory allocated for the cache_handle.
166
* - mark the handle as "not initialized".
167
*
168
* Parameters:
169
* cache_handle: Handler to the opened cahe directory to use.
170
*
171
* cache_handle->is_init set to "not initialized" and all the
172
* files opened bu globus_gass_cache_open are closed .
173
*
174
* Returns:
175
* GLOBUS_SUCCESS or error code:
176
* GLOBUS_GASS_CACHE_ERROR_CACHE_NOT_OPENED
177
*
178
*/
179
extern int
180
globus_gass_cache_close(globus_gass_cache_t * cache_handle);
181
182
/*
183
* globus_gass_cache_add()
184
*
185
* Create a new cache file or add a tag on it.
186
*
187
* If the URL is already in the cache but is locked, then this call will block
188
* until the cache entry is unlocked, then will proceed with the subsequent
189
* operations.
190
*
191
* If the URL is already in the cache and unlocked, then add the tag to the
192
* cache entry's tag list, return the local cache filename in *local_filename,
193
* return the entry's current timestamp in *timestamp, lock the cache entry,
194
* and return GLOBUS_GASS_CACHE_ADD_EXISTS.
195
*
196
* If the URL is not in the cache, and create==GLOBUS_TRUE, then create a new
197
* unique empty local cache file, add it to the cache with the specified tag,
198
* return the filename in *local_filename, return *timestamp set to
199
* GLOBUS_GASS_TIMESTAMP_UNKNOWN, lock the cache entry, and
200
* return GLOBUS_GASS_CACHE_ADD_NEW.
201
*
202
* If the URL is not in the cache, and create==GLOBUS_FALSE, then do not
203
* add it to the cache, and return GLOBUS_GASS_CACHE_URL_NOT_FOUND.
204
*
205
* If this function returns GLOBUS_GASS_CACHE_ADD_EXISTS or
206
* GLOBUS_GASS_CACHE_ADD_NEW, then globus_gass_cache_add_done() or
207
* globus_gass_cache_delete() must be subsequently
208
* called to unlock the cache entry.
209
*
210
* Subsequent calls to globus_gass_cache_add() and
211
* globus_gass_cache_delete_start() on the same cache and url, made either
212
* from this process or another, will block until the cache entry is unlocked.
213
*
214
* If tag==NULL, then a tag with the value "null" will be added to the cache
215
* entry's tag list.
216
*
217
* The same tag can be used multiple times, in which case this tag will be
218
* added to the entry's tag list multiple times.
219
*
220
* Note: It is recommended that proglobus_grams started via GLOBUS_GRAM
221
* pass a tag value
222
* of getenv("GLOBUS_GRAM_JOB_CONTACT"), since upon completion of a
223
* job GLOBUS_GRAM will automatically cleanup entries with this tag.
224
*
225
* Important Note: the local_filename MUST be free by the user in a
226
* subsequent operation, using globus_free()
227
*
228
* Parameters:
229
*
230
* cache_handle - Handler to the opened cahe directory to use.
231
*
232
* url - url of the file to be cached. It is used as the main
233
* key to the cache entries.
234
*
235
* tag - tag specifying which job is/are using the cache. This
236
* is usually the GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the
237
* tag "null" is then used.
238
* create - Tells if the cache entry should be created if it is
239
* not already existing.
240
*
241
* timestamp - time stamp of the cached file, set by
242
* globus_gass_cache_done(), (or globus_gass_cache_delete() ).
243
*
244
* local_filename - Path the the local file caching the file
245
* specified by "url". NULL if "url" not yet cached and
246
* creation not requested (create false).
247
*
248
* Returns:
249
* GLOBUS_GASS_CACHE_URL_NOT_FOUND
250
* GLOBUS_GASS_CACHE_ADD_NEW
251
* GLOBUS_GASS_CACHE_ADD_EXISTS
252
* or any of the defined gass error code.
253
*
254
*/
255
extern
256
int
257
globus_gass_cache_add(globus_gass_cache_t cache_handle,
258
const char *url,
259
const char *tag,
260
globus_bool_t create,
261
unsigned long *timestamp,
262
char **local_filename);
263
264
/*
265
* globus_gass_cache_add_done()
266
*
267
* globus_gass_cache_add_done() MUST be called after globus_gass_cache_add(),
268
* to set the timestamp in the cache entry for the URL, and then unlock the
269
* cache entry. (The only case it does not need to be called is if
270
* globus_gass_cache_add() has returned GLOBUS_GASS_CACHE_URL_NOT_FOUND, of
271
* course.
272
*
273
* Parameters:
274
* cache_handle - Handler to the opened cahe directory to use.
275
*
276
* url - url of the cached file to set as "done" (unlock)
277
* tag - tag specifying which job has locked the cache and must
278
* therfor be unlocked.It is an error to call this function
279
* with a tag which does not currently own the cache lock.
280
* timestamp: time stamp of the cached file.
281
*
282
*
283
* Returns:
284
* GLOBUS_SUCCESS or error code:
285
* or any of the defined gass error code.
286
*/
287
extern int
288
globus_gass_cache_add_done(
289
globus_gass_cache_t cache_handle,
290
const char *url,
291
const char *tag,
292
unsigned long timestamp);
293
294
/*
295
* globus_gass_cache_query()
296
*
297
* Query if an item is in the cache
298
*
299
* This call will block only if wait_for_lock is GLOBUS_TRUE
300
*
301
* Parameters:
302
*
303
* cache_handle - Handler to the opened cahe directory to use.
304
*
305
* url - url of the file to query. It is used as the main
306
* key to the cache entries.
307
*
308
* tag - tag specifying which job is/are using the cache. This
309
* is usually the GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the
310
* tag "null" is then used.
311
* create - Tells if the cache entry should be created if it is
312
* not already existing.
313
*
314
* wait_for_lock - If GLOBUS_TRUE, wait for any lock existing lock
315
* to be released. If GLOBUS_FALSE, doesn't wait for a lock to be
316
* released.
317
*
318
* timestamp - time stamp of the cached file, set by
319
* globus_gass_cache_done(), (or globus_gass_cache_delete() ).
320
*
321
* local_filename - Path the the local file caching the file
322
* specified by "url". NULL if "url" not yet cached and
323
* creation not requested (create false).
324
*
325
* is_locked - GLOBUS_TRUE if the file is currently (at return
326
* time) locked.
327
*
328
* Returns:
329
* GLOBUS_SUCCESS
330
* GLOBUS_GASS_CACHE_URL_NOT_FOUND
331
* or any of the defined gass error code.
332
*
333
*/
334
int
335
globus_gass_cache_query(
336
globus_gass_cache_t cache_handle,
337
const char *url,
338
const char *tag,
339
globus_bool_t wait_for_lock,
340
unsigned long *timestamp,
341
char **local_filename,
342
globus_bool_t *is_locked );
343
344
345
/*
346
* globus_gass_cache_delete()
347
*
348
* Remove one instance of the tag from the cache entry's tag list.
349
*
350
* If there are no more tags in the tag list, then remove this cache
351
* entry and delete the associated local cache file.
352
*
353
* Otherwise, update the timestamp to the passed value.
354
*
355
* This call will leave the cache entry unlocked.
356
*
357
* If is_locked==GLOBUS_TRUE, then this cache entry was locked during a
358
* previous call to globus_gass_cache_add() or
359
* globus_gass_cache_delete_start(). The cache
360
* file should be locked by the corresponding url/tag, or an error is
361
* returned. If it is locked by the corresponding url/tag, then the normal
362
* operation occur, whithout blocking (remove one instance from the tag
363
* update the timestamp and unlock the cache).
364
*
365
* If is_locked==GLOBUS_FALSE, eventually wait the cache is not locked any
366
* more, and then proceed with the normal operations.(remove one instance
367
* from the tag list and update the timestamp).
368
*
369
* Parameters:
370
* cache_handle - Handler to the opened cahe directory to use.
371
*
372
* url - url of the file to be cached. It is used as the main
373
* key to the cache entries.
374
*
375
* tag - tag specifying which job is/are using the cache. This
376
* is usually the GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the
377
* tag "null" is then used.
378
*
379
* timestamp - time stamp of the cached file.
380
*
381
* is_locked - indicate if this cache entry was locked during a
382
* previous call to globus_gass_cache_add() or
383
* globus_gass_cache_delete_start().
384
*
385
*
386
* Returns:
387
* GLOBUS_SUCCESS or error code:
388
* or any of the defined gass error code.
389
*/
390
391
extern
392
int
393
globus_gass_cache_delete_start(
394
globus_gass_cache_t cache_handle,
395
const char *url,
396
const char *tag,
397
unsigned long *timestamp);
398
399
extern
400
int
401
globus_gass_cache_delete(
402
globus_gass_cache_t cache_handle,
403
const char *url,
404
const char *tag,
405
unsigned long timestamp,
406
globus_bool_t is_locked);
407
408
/*
409
* globus_gass_cache_cleanup_tag()
410
*
411
* Remove all instances of the tag from the cache entry's tag list.
412
* If there are no more tags in the tag list, then remove this cache entry
413
* and delete the associated local cache file.
414
* If the cache entry is locked with the same tag as is passed to this
415
* function, then the entry is unlocked after removing the tags.
416
* Otherwise, the cache entry's lock is left untouched.
417
*
418
* This function does not block on a locked reference.
419
*
420
* Note: The GLOBUS_GRAM job manager will automatically call this function
421
* with a tag of getenv("GLOBUS_GRAM_JOB_CONTACT") upon completion of a job.
422
*
423
* Parameters:
424
*
425
* cache_handle - Handler to the opened cahe directory to use.
426
*
427
* url - url of the file to be cached. It is used as the main
428
* key to the cache entries.
429
*
430
* tag - tag specifying which job is/are using the cache. This
431
* is usually the GLOBUS_GRAM_JOB_CONTACT. Can be NULL or empty; the
432
* tag "null" is then used.
433
*
434
*
435
* Returns:
436
* GLOBUS_SUCCESS or error code:
437
* or any of the defined gass error code.
438
*/
439
extern
440
int
441
globus_gass_cache_cleanup_tag(
442
globus_gass_cache_t cache_handle,
443
const char *url,
444
const char *tag);
445
446
extern
447
int
448
globus_gass_cache_cleanup_tag_all(
449
globus_gass_cache_t cache_handle,
450
char *tag );
451
452
/*
453
* globus_l_gass_cache_mangle_url()
454
*
455
* Mangles the given URL into a chunk suitable for using as a file /
456
* path name.
457
*
458
* Parameters:
459
* cache_handle - Handler to the opened cahe directory to use.
460
*
461
* url - The incoming URL to mangle (\0 terminated)
462
*
463
* mangled_url - Pointer to the output string; a buffer for the
464
* real string is malloc()ed for the application. If mangled is
465
* NULL, then no such buffer is allocated, and no mangled string
466
* is created. This can be useful to just get the length of the
467
* mangled string.
468
*
469
* Length - The length of the resulting string. If NULL, this is
470
* not assigned to.
471
*
472
* Returns:
473
* GLOBUS_SUCCESS
474
* GLOBUS_GASS_CACHE_ERROR_NO_MEMORY
475
*
476
*/
477
int
478
globus_gass_cache_mangle_url( const globus_gass_cache_t cache_handle,
479
const char *url,
480
char **mangled_url,
481
int *length );
482
483
/*
484
* globus_l_gass_cache_mangle_tag()
485
*
486
* Mangles the given tag into a chunk suitable for using as a file /
487
* path name.
488
*
489
* Parameters:
490
* cache_handle - Handler to the opened cahe directory to use.
491
*
492
* tag - The incoming tag to mangle (\0 terminated)
493
*
494
* mangled_tag - Pointer to the output string; a buffer for the
495
* real string is malloc()ed for the application. If mangled is
496
* NULL, then no such buffer is allocated, and no mangled string
497
* is created. This can be useful to just get the length of the
498
* mangled string.
499
*
500
* Length - The length of the resulting string. If NULL, this is
501
* not assigned to.
502
*
503
* Returns:
504
* GLOBUS_SUCCESS
505
* GLOBUS_GASS_CACHE_ERROR_NO_MEMORY
506
*
507
*/
508
int
509
globus_gass_cache_mangle_tag( const globus_gass_cache_t cache_handle,
510
const char *tag,
511
char **mangled_tag,
512
int *length );
513
514
/*
515
* globus_gass_cache_get_dirs()
516
*
517
* Gets a bunch of directories. This is exported for use in the
518
* globus_gass_cache program.
519
*
520
* Parameters:
521
* cache_handle - Handler to the opened cahe directory to use.
522
*
523
* URL - The incoming URL
524
*
525
* tag - The incoming tag
526
*
527
* local_root - Pointer to the "local root" directory
528
*
529
* global_root - Pointer to the "global root" directory
530
*
531
* tmp_root - Pointer to the "tmp root" directory
532
*
533
* log_root - Pointer to the root log directory
534
*
535
* local_dir - Pointer to the related "local" directory
536
*
537
* global_dir - Pointer to the related "global" directory
538
*
539
* Returns:
540
* GLOBUS_SUCCESS
541
* GLOBUS_GASS_CACHE_ERROR_NO_MEMORY
542
*
543
*/
544
int
545
globus_gass_cache_get_dirs( const globus_gass_cache_t cache_handle,
546
const char *url,
547
const char *tag,
548
char **global_root,
549
char **local_root,
550
char **tmp_root,
551
char **log_root,
552
char **global_dir,
553
char **local_dir );
554
555
/*
556
* globus_gass_cache_get_cache_dir()
557
*
558
* Gets a the root cache of directory. This is exported for use in the
559
* globus_gass_cache program.
560
*
561
* Parameters:
562
* cache_handle - Handler to the opened cahe directory to use.
563
*
564
* cache_dir - Pointer to the cache directory
565
*
566
* Returns:
567
* GLOBUS_SUCCESS
568
* GLOBUS_GASS_CACHE_ERROR_NO_MEMORY
569
*
570
*/
571
int
572
globus_gass_cache_get_cache_dir( const globus_gass_cache_t cache_handle,
573
char **cache_dir );
574
575
/*
576
* globus_gass_cache_get_cache_type_string()
577
*
578
* Gets a string which describes the cache type ("normal" or "flat")
579
*
580
* Parameters:
581
* cache_handle - Handler to the opened cahe directory to use.
582
*
583
* cache_type - Pointer to the strdup()ed string
584
*
585
* Returns:
586
* GLOBUS_SUCCESS
587
* GLOBUS_GASS_CACHE_ERROR_NO_MEMORY
588
*
589
*/
590
int
591
globus_gass_cache_get_cache_type_string( const globus_gass_cache_t cache_handle,
592
char **cache_type );
593
594
/*
595
* globus_gass_cache_error_string()
596
*
597
* Return a pointer on an error description string.
598
*
599
*Parameters:
600
* error_code: error code returned by a previously called
601
* globus_gass_cache function.
602
*
603
* Returns:
604
* Pointer to an error message, or NULL if invalide error code.
605
*/
606
extern
607
const
608
char *
609
globus_gass_cache_error_string(
610
int error_code);
611
612
EXTERN_C_END
613
614
/*
615
* Module Definition
616
*/
617
618
#define GLOBUS_GASS_CACHE_MODULE (&globus_i_gass_cache_module)
619
620
extern globus_module_descriptor_t globus_i_gass_cache_module;
621
622
623
#endif /* _GLOBUS_GASS_INCLUDE_GLOBUS_GASS_CACHE_H */
Loggerhead is a web-based interface for Breezy
Version: 2.0.1