BRL-CAD
mapped_file.h
Go to the documentation of this file.
1 /* M A P P E D _ F I L E . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * 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 file; see the file named COPYING for more
18  * information.
19  */
20 
21 /** @file mapped_file.h
22  *
23  */
24 #ifndef BU_MAPPED_FILE_H
25 #define BU_MAPPED_FILE_H
26 
27 #include "common.h"
28 
29 #include <sys/types.h> /* for time_t */
30 #include <stddef.h> /* for size_t */
31 
32 #include "bu/defines.h"
33 #include "bu/magic.h"
34 #include "bu/list.h"
35 
37 
38 /** @addtogroup mf */
39 /** @{ */
40 /** @file libbu/mappedfile.c
41  *
42  * Routines for sharing large read-only data files.
43  *
44  * Routines for sharing large read-only data files like height fields,
45  * bit map solids, texture maps, etc. Uses memory mapped files where
46  * available.
47  *
48  * Each instance of the file has the raw data available as element
49  * "buf". If a particular application needs to transform the raw data
50  * in a manner that is identical across all uses of that application
51  * (e.g. height fields, EBMs, etc.), then the application should
52  * provide a non-null "appl" string, to tag the format of the "apbuf".
53  * This will keep different applications from sharing that instance of
54  * the file.
55  *
56  * Thus, if the same filename is opened for interpretation as both an
57  * EBM and a height field, they will be assigned different mapped file
58  * structures, so that the "apbuf" pointers are distinct.
59  *
60  */
61 
62 /**
63  * @struct bu_mapped_file bu.h
64  *
65  * Structure for opening a mapped file.
66  *
67  * Each file is opened and mapped only once (per application, as
68  * tagged by the string in "appl" field). Subsequent opens require an
69  * exact match on both strings.
70  *
71  * Before allocating apbuf and performing data conversion into it,
72  * openers should check to see if the file has already been opened and
73  * converted previously.
74  *
75  * When used in RT, the mapped files are not closed at the end of a
76  * frame, so that subsequent frames may take advantage of the large
77  * data files having already been read and converted. Examples
78  * include EBMs, texture maps, and height fields.
79  *
80  * For appl == "db_i", file is a ".g" database & apbuf is (struct db_i *).
81  */
83  struct bu_list l;
84  char *name; /**< bu_strdup() of file name */
85  void *buf; /**< In-memory copy of file (may be mmapped) */
86  size_t buflen; /**< # bytes in 'buf' */
87  int is_mapped; /**< 1=mmap() used, 0=bu_malloc/fread */
88  char *appl; /**< bu_strdup() of tag for application using 'apbuf' */
89  void *apbuf; /**< opt: application-specific buffer */
90  size_t apbuflen; /**< opt: application-specific buflen */
91  time_t modtime; /**< date stamp, in case file is modified */
92  int uses; /**< # ptrs to this struct handed out */
93  int dont_restat; /**< 1=on subsequent opens, don't re-stat() */
94 };
96 #define BU_MAPPED_FILE_NULL ((struct bu_mapped_file *)0)
97 
98 /**
99  * assert the integrity of a bu_mapped_file struct.
100  */
101 #define BU_CK_MAPPED_FILE(_mf) BU_CKMAG(_mf, BU_MAPPED_FILE_MAGIC, "bu_mapped_file")
102 
103 /**
104  * initialize a bu_mapped_file struct without allocating any memory.
105  */
106 #define BU_MAPPED_FILE_INIT(_mf) { \
107  BU_LIST_INIT_MAGIC(&(_mf)->l, BU_MAPPED_FILE_MAGIC); \
108  (_mf)->name = (_mf)->buf = NULL; \
109  (_mf)->buflen = (_mf)->is_mapped = 0; \
110  (_mf)->appl = (_mf)->apbuf = NULL; \
111  (_mf)->apbuflen = (_mf)->modtime = (_mf)->uses = (_mf)->dont_restat = 0; \
112  }
113 
114 /**
115  * macro suitable for declaration statement initialization of a
116  * bu_mapped_file struct. does not allocate memory.
117  */
118 #define BU_MAPPED_FILE_INIT_ZERO { {BU_MAPPED_FILE_MAGIC, BU_LIST_NULL, BU_LIST_NULL}, NULL, NULL, 0, 0, NULL, NULL, 0, 0, 0, 0 }
119 
120 /**
121  * returns truthfully whether a bu_mapped_file has been initialized via
122  * BU_MAPPED_FILE_INIT() or BU_MAPPED_FILE_INIT_ZERO.
123  */
124 #define BU_MAPPED_FILE_IS_INITIALIZED(_hp) (((struct bu_mapped_file *)(_hp) != BU_MAPPED_FILE_NULL) && LIKELY((_hp)->l.magic == BU_MAPPED_FILE_MAGIC))
125 
126 
127 /**
128  * Provides a standardized interface for acquiring the entire contents
129  * of an existing file mapped into the current address space, using
130  * the virtual memory capabilities of the operating system (such as
131  * mmap()) where available, or by allocating sufficient dynamic memory
132  * and reading the entire file.
133  *
134  * If the file can not be opened, as descriptive an error message as
135  * possible will be printed, to simplify code handling in the caller.
136  *
137  * Mapped files are always opened read-only.
138  *
139  * If the system does not support mapped files, the data is read into
140  * memory.
141  */
142 BU_EXPORT extern struct bu_mapped_file *bu_open_mapped_file(const char *name,
143  const char *appl);
144 
145 /**
146  * Release a use of a mapped file. Because it may be re-used shortly,
147  * e.g. by the next frame of an animation, don't release the memory
148  * even on final close, so that it's available when next needed.
149  *
150  * Call bu_free_mapped_files() after final close to reclaim space.
151  * But only do that if you're SURE that ALL these files will never
152  * again need to be mapped by this process. Such as when running
153  * multi-frame animations.
154  */
155 BU_EXPORT extern void bu_close_mapped_file(struct bu_mapped_file *mp);
156 
157 BU_EXPORT extern void bu_pr_mapped_file(const char *title,
158  const struct bu_mapped_file *mp);
159 
160 /**
161  * Release storage being used by mapped files with no remaining users.
162  * This entire routine runs inside a critical section, for parallel
163  * protection. Only call this routine if you're SURE that ALL these
164  * files will never again need to be mapped by this process. Such as
165  * when running multi-frame animations.
166  */
167 BU_EXPORT extern void bu_free_mapped_files(int verbose);
168 
169 /**
170  * A wrapper for bu_open_mapped_file() which uses a search path to
171  * locate the file.
172  *
173  * The search path is specified as a normal C argv array, terminated
174  * by a null string pointer. If the file name begins with a slash
175  * ('/') the path is not used.
176  */
177 BU_EXPORT extern struct bu_mapped_file *bu_open_mapped_file_with_path(char * const *path,
178  const char *name,
179  const char *appl);
180 
181 /** @} */
182 
184 
185 #endif /* BU_MAPPED_FILE_H */
186 
187 /*
188  * Local Variables:
189  * mode: C
190  * tab-width: 8
191  * indent-tabs-mode: t
192  * c-file-style: "stroustrup"
193  * End:
194  * ex: shiftwidth=4 tabstop=8
195  */
Definition: list.h:118
Definition: clone.c:90
void bu_pr_mapped_file(const char *title, const struct bu_mapped_file *mp)
Definition: mappedfile.c:358
Header file for the BRL-CAD common definitions.
time_t modtime
Definition: mapped_file.h:91
size_t apbuflen
Definition: mapped_file.h:90
#define __BEGIN_DECLS
Definition: common.h:73
struct bu_mapped_file * bu_open_mapped_file(const char *name, const char *appl)
Definition: mappedfile.c:56
struct bu_list l
Definition: mapped_file.h:83
void bu_free_mapped_files(int verbose)
Definition: mappedfile.c:373
void bu_close_mapped_file(struct bu_mapped_file *mp)
Definition: mappedfile.c:339
#define __END_DECLS
Definition: common.h:74
HIDDEN void verbose(struct human_data_t *dude)
Definition: human.c:2008
struct bu_mapped_file * bu_open_mapped_file_with_path(char *const *path, const char *name, const char *appl)
Definition: mappedfile.c:430