Memory-mapped Files

Routines for sharing large read-only data files. More...

Collaboration diagram for Memory-mapped Files:

Files
file	mapped_file.h

Data Structures
struct	bu_mapped_file

Macros
#define	BU_MAPPED_FILE_NULL   ((struct bu_mapped_file *)0)
#define	BU_MAPPED_FILE_INIT_ZERO   { NULL, NULL, 0, 0, NULL, NULL, 0, 0, 0, NULL }

Typedefs
typedef struct bu_mapped_file	bu_mapped_file_t

Functions
struct bu_mapped_file *	bu_open_mapped_file (const char *name, const char *appl)
void	bu_close_mapped_file (struct bu_mapped_file *mp)
void	bu_pr_mapped_file (const char *title, const struct bu_mapped_file *mp)
void	bu_free_mapped_files (int verbose)
struct bu_mapped_file *	bu_open_mapped_file_with_path (char *const *path, const char *name, const char *appl)

Detailed Description

Routines for sharing large read-only data files.

Typical use cases include height fields, bit map solids, texture maps, etc. Uses memory mapped files where available.

Each instance of the file has the raw data available as element "buf". If a particular application needs to transform the raw data in a manner that is identical across all uses of that application (e.g. height fields, EBMs, etc.), then the application should provide a non-null "appl" string, to tag the format of the "apbuf". This will keep different applications from sharing that instance of the file.

Thus, if the same filename is opened for interpretation as both an EBM and a height field, they will be assigned different mapped file structures, so that the "apbuf" pointers are distinct.

Macro Definition Documentation

BU_MAPPED_FILE_NULL

#define BU_MAPPED_FILE_NULL   ((struct bu_mapped_file *)0)

Definition at line 94 of file mapped_file.h.

BU_MAPPED_FILE_INIT_ZERO

#define BU_MAPPED_FILE_INIT_ZERO   { NULL, NULL, 0, 0, NULL, NULL, 0, 0, 0, NULL }

macro suitable for declaration statement initialization of a bu_mapped_file struct. does not allocate memory.

Definition at line 100 of file mapped_file.h.

Typedef Documentation

bu_mapped_file_t

typedef struct bu_mapped_file bu_mapped_file_t

Definition at line 93 of file mapped_file.h.

Function Documentation

bu_open_mapped_file()

struct bu_mapped_file * bu_open_mapped_file	(	const char *	name,
		const char *	appl
	)

Provides a standardized interface for acquiring the entire contents of an existing file mapped into the current address space, using the virtual memory capabilities of the operating system (such as mmap()) where available, or by allocating sufficient dynamic memory and reading the entire file.

If the file can not be opened, as descriptive an error message as possible will be printed, to simplify code handling in the caller.

Mapped files are always opened read-only.

If the system does not support mapped files, the data is read into memory.

bu_close_mapped_file()

void bu_close_mapped_file

(

struct bu_mapped_file *

mp

)

Release a use of a mapped file. Because it may be re-used shortly, e.g. by the next frame of an animation, don't release the memory even on final close, so that it's available when next needed.

Call bu_free_mapped_files() after final close to reclaim space. But only do that if you're SURE that ALL these files will never again need to be mapped by this process. Such as when running multi-frame animations.

bu_pr_mapped_file()

void bu_pr_mapped_file	(	const char *	title,
		const struct bu_mapped_file *	mp
	)

bu_free_mapped_files()

void bu_free_mapped_files

(

int

verbose

)

Release storage being used by mapped files with no remaining users. This will slow subsequent re-opening of those files (since files with no users will be unmapped as part of the freeing process, they will have to be re-mapped on a subsequent reopen.) Use cases where there is a possibility of reopening such files in the future will generally want to postpone calling this routine unless they need to free up memory.

This entire routine runs inside a critical section, for parallel protection.

bu_open_mapped_file_with_path()

struct bu_mapped_file * bu_open_mapped_file_with_path	(	char *const *	path,
		const char *	name,
		const char *	appl
	)

A wrapper for bu_open_mapped_file() which uses a search path to locate the file.

The search path is specified as a normal C argv array, terminated by a null string pointer. If the file name begins with a slash ('/') the path is not used.