1 /*
2  * virfilecache.h: file caching for data
3  *
4  * Copyright (C) 2017 Red Hat, Inc.
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library.  If not, see
18  * <http://www.gnu.org/licenses/>.
19  *
20  */
21 
22 #pragma once
23 
24 #include "internal.h"
25 
26 #include "virobject.h"
27 #include "virhash.h"
28 
29 typedef struct _virFileCache virFileCache;
30 
31 /**
32  * virFileCacheIsValidPtr:
33  * @data: data object to validate
34  * @priv: private data created together with cache
35  *
36  * Validates the cached data whether it needs to be refreshed
37  * or no.
38  *
39  * Returns *true* if it's valid or *false* if not valid.
40  */
41 typedef bool
42 (*virFileCacheIsValidPtr)(void *data,
43                           void *priv);
44 
45 /**
46  * virFileCacheNewDataPtr:
47  * @name: name of the new data
48  * @priv: private data created together with cache
49  *
50  * Creates a new data based on the @name.  The returned data must be
51  * an instance of virObject.
52  *
53  * Returns data object or NULL on error.
54  */
55 typedef void *
56 (*virFileCacheNewDataPtr)(const char *name,
57                           void *priv);
58 
59 /**
60  * virFileCacheLoadFilePtr:
61  * @filename: name of a file with cached data
62  * @name: name of the cached data
63  * @priv: private data created together with cache
64  * @outdated: set to true if data was outdated
65  *
66  * Loads the cached data from a file @filename. If
67  * NULL is returned, then @oudated indicates whether
68  * this was due to the data being outdated, or an
69  * error loading the cache.
70  *
71  * Returns cached data object or NULL on outdated data or error.
72  */
73 typedef void *
74 (*virFileCacheLoadFilePtr)(const char *filename,
75                            const char *name,
76                            void *priv,
77                            bool *outdated);
78 
79 /**
80  * virFileCacheSaveFilePtr:
81  * @data: data object to save into a file
82  * @filename: name of the file where to store the cached data
83  * @priv: private data created together with cache
84  *
85  * Stores the cached to a file @filename.
86  *
87  * Returns 0 on success, -1 on error.
88  */
89 typedef int
90 (*virFileCacheSaveFilePtr)(void *data,
91                            const char *filename,
92                            void *priv);
93 
94 /**
95  * virFileCachePrivFreePtr:
96  * @priv: private data created together with cache
97  *
98  * This is used to free the private data when the cache object
99  * is removed.
100  */
101 typedef void
102 (*virFileCachePrivFreePtr)(void *priv);
103 
104 typedef struct _virFileCacheHandlers virFileCacheHandlers;
105 struct _virFileCacheHandlers {
106     virFileCacheIsValidPtr isValid;
107     virFileCacheNewDataPtr newData;
108     virFileCacheLoadFilePtr loadFile;
109     virFileCacheSaveFilePtr saveFile;
110     virFileCachePrivFreePtr privFree;
111 };
112 
113 virFileCache *
114 virFileCacheNew(const char *dir,
115                 const char *suffix,
116                 virFileCacheHandlers *handlers);
117 
118 void *
119 virFileCacheLookup(virFileCache *cache,
120                    const char *name);
121 
122 void *
123 virFileCacheLookupByFunc(virFileCache *cache,
124                          virHashSearcher iter,
125                          const void *iterData);
126 
127 void *
128 virFileCacheGetPriv(virFileCache *cache);
129 
130 void
131 virFileCacheSetPriv(virFileCache *cache,
132                     void *priv);
133 
134 int
135 virFileCacheInsertData(virFileCache *cache,
136                        const char *name,
137                        void *data);
138