Lumiera  0.pre.03
»edityourfreedom«
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
file.h File Reference

Go to the source code of this file.

Description

File management.

Handling Files is split into different classes:

  1. The 'lumiera_file' class which acts as interface to the outside for managing files. 'lumiera_file' is addressed by the name of the file. Since files can have more than one name (hardlinks) many 'lumiera_file' can point to a single 'lumiera_filedescriptor'
  2. The 'lumiera_filedescriptor' class which does the real work managing the file in the back.
  3. Since OS-filehandles are a limited resource we access the lazily as 'lumiera_filehandle' which are managed in a 'lumiera_filehandlecache'

Definition in file file.h.

#include "lib/mutex.h"
#include "lib/llist.h"
#include "lib/error.h"
#include "backend/filedescriptor.h"
#include "backend/filehandle.h"
#include "backend/mmapings.h"
#include "backend/mmap.h"

Classes

struct  lumiera_file
 

Typedefs

typedef lumiera_file * LumieraFile
 

Macros

#define LUMIERA_FILE_CREATE
 
#define LUMIERA_FILE_MASK
 
#define LUMIERA_FILE_MMAP_SECTION(nobugflag, file, start, size, addr)
 helper macro for acquiring and releasing maped regions More...
 
#define LUMIERA_FILE_RDLOCK_SECTION(nobugflag, file)
 
#define LUMIERA_FILE_READONLY
 File modes: More...
 
#define LUMIERA_FILE_READWRITE
 
#define LUMIERA_FILE_RECREATE
 
#define LUMIERA_FILE_WRLOCK_SECTION(nobugflag, file)
 

Functions

 LUMIERA_ERROR_DECLARE (FILE_CHANGED)
 
 LUMIERA_ERROR_DECLARE (FILE_NOMMAPINGS)
 
size_t lumiera_file_bias_get (LumieraFile self)
 Get the bias for mapping operations. More...
 
int lumiera_file_checkflags (LumieraFile self, int flags)
 Query the flags effective for a file. More...
 
size_t lumiera_file_chunksize_get (LumieraFile self)
 Get the chunksize for mapping operations. More...
 
void lumiera_file_delete (LumieraFile self)
 Frees a file structure. More...
 
void lumiera_file_delete_unlink (LumieraFile self)
 Frees a file structure and deletes the associated file name from disk. More...
 
LumieraFile lumiera_file_destroy (LumieraFile self, int do_unlink)
 Destroy a file structure. More...
 
int lumiera_file_handle_acquire (LumieraFile self)
 Get a POSIX filehandle for a file. More...
 
void lumiera_file_handle_release (LumieraFile self)
 Put filehandle back into cache aging. More...
 
LumieraFile lumiera_file_init (LumieraFile self, const char *name, int flags)
 Initialise a file structure. More...
 
LumieraMMap lumiera_file_mmap_acquire (LumieraFile self, off_t start, size_t size)
 acquire a mmap which covers the given range More...
 
LumieraMMapings lumiera_file_mmapings (LumieraFile self)
 Query the underlying mmapings object from a file The MMapings only exists after a chunksize got set with lumiera_file_chunksize_set() More...
 
LumieraFile lumiera_file_new (const char *name, int flags)
 Allocate a new file structure. More...
 
LumieraFile lumiera_file_rdlock (LumieraFile self)
 Place and remove locks on a file. More...
 
void lumiera_file_release_mmap (LumieraFile self, LumieraMMap map)
 release a previously acquired MMap object More...
 
size_t lumiera_file_set_chunksize_bias (LumieraFile self, size_t chunksize, size_t bias)
 Set the chunksize for mapping operations can only set once for a file descriptor, subsequent calls are no-ops. More...
 
LumieraFile lumiera_file_unlock (LumieraFile self)
 
LumieraFile lumiera_file_wrlock (LumieraFile self)
 

Typedef Documentation

typedef lumiera_file* LumieraFile

Definition at line 49 of file file.h.

Macro Definition Documentation

#define LUMIERA_FILE_READONLY

File modes:

  • LUMIERA_FILE_READONLY existing file for reading only
  • LUMIERA_FILE_READWRITE existing file for reading and writing
  • LUMIERA_FILE_CREATE non-existing file for reading and writing
  • LUMIERA_FILE_RECREATE remove and recreated existing, file for reading and writing

Definition at line 64 of file file.h.

Referenced by TEST().

#define LUMIERA_FILE_READWRITE

Definition at line 65 of file file.h.

Referenced by TEST().

#define LUMIERA_FILE_CREATE

Definition at line 66 of file file.h.

Referenced by TEST().

#define LUMIERA_FILE_RECREATE

Definition at line 67 of file file.h.

Referenced by TEST().

#define LUMIERA_FILE_MASK

Definition at line 70 of file file.h.

Referenced by cmp_fn(), and lumiera_filehandle_handle().

#define LUMIERA_FILE_MMAP_SECTION (   nobugflag,
  file,
  start,
  size,
  addr 
)

helper macro for acquiring and releasing maped regions

Parameters
nobugflagunused for now
filethe file from from where to acquire the mapped region
startthe start offset for the mmaped region
sizethe length of the requested block
addrname of a void* variable pointing to the requested memory

Definition at line 180 of file file.h.

Referenced by TEST().

#define LUMIERA_FILE_RDLOCK_SECTION (   nobugflag,
  file 
)

Definition at line 259 of file file.h.

Referenced by TEST().

#define LUMIERA_FILE_WRLOCK_SECTION (   nobugflag,
  file 
)

Definition at line 268 of file file.h.

Referenced by TEST().


Class Documentation

struct lumiera_file_struct
Class Members
llist node
char * name
LumieraFiledescriptor descriptor
+ Collaboration diagram for lumiera_file:

Function Documentation

LUMIERA_ERROR_DECLARE ( FILE_CHANGED  )
LUMIERA_ERROR_DECLARE ( FILE_NOMMAPINGS  )
LumieraFile lumiera_file_init ( LumieraFile  self,
const char *  name,
int  flags 
)

Initialise a file structure.

Parameters
selfpointer to the file structure
namefilename
flagsopen flags
Returns
self or NULL in case of an error

Definition at line 46 of file file-handling.c.

References lumiera_filedescriptor_acquire(), lumiera_strndup(), NULL, and TRACE().

Referenced by lumiera_file_new().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

LumieraFile lumiera_file_destroy ( LumieraFile  self,
int  do_unlink 
)

Destroy a file structure.

frees all associated resources, releases the file descriptor etc.

Parameters
selffile structure to be destroyed
do_unlinkif 1 then delete the file physically from disk (only the associated name)
Returns
self

Definition at line 64 of file file-handling.c.

References lumiera_filedescriptor_release(), lumiera_free(), and TRACE().

Referenced by lumiera_file_delete(), and lumiera_file_delete_unlink().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

LumieraFile lumiera_file_new ( const char *  name,
int  flags 
)

Allocate a new file structure.

Parameters
namefilename
flagsopen flags
Returns
new file structure or NULL in case of an error

Definition at line 78 of file file-handling.c.

References lumiera_file_init(), lumiera_free(), lumiera_malloc(), NULL, and TRACE().

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void lumiera_file_delete ( LumieraFile  self)

Frees a file structure.

Parameters
selffile structure to be freed

Definition at line 94 of file file-handling.c.

References lumiera_file_destroy(), lumiera_free(), and TRACE().

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void lumiera_file_delete_unlink ( LumieraFile  self)

Frees a file structure and deletes the associated file name from disk.

Parameters
selffile structure to be freed

Definition at line 103 of file file-handling.c.

References lumiera_file_destroy(), lumiera_free(), and TRACE().

+ Here is the call graph for this function:

int lumiera_file_handle_acquire ( LumieraFile  self)

Get a POSIX filehandle for a file.

Filehandles are opened on demand and must be acquired for use. The use of filehandles is refcounted and might be nested. After using them they must be released which puts them back into filehandle cache aging.

Parameters
selffile structure
Returns
POSIX filehandle or -1 on error, check lumiera_error() to retrieve the errorcode Currently only LUMIERA_ERROR_ERRNO will be raised but this might change in future. Opening files can fail for many reasons and at any time!

Definition at line 112 of file file-handling.c.

References lumiera_filedescriptor_handle_acquire(), and TRACE().

Referenced by lumiera_mmap_init(), lumiera_mmap_init_exact(), and TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void lumiera_file_handle_release ( LumieraFile  self)

Put filehandle back into cache aging.

Parameters
selffile which handle to be released

Definition at line 123 of file file-handling.c.

References lumiera_filedescriptor_handle_release(), and TRACE().

Referenced by lumiera_mmap_init(), lumiera_mmap_init_exact(), and TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

LumieraMMap lumiera_file_mmap_acquire ( LumieraFile  self,
off_t  start,
size_t  size 
)

acquire a mmap which covers the given range

Parameters
selffile from where the mmap shall be acquired
startbegin of the required range
sizerequested size
Returns
MMap object covering the requested range or NULL on error note: the chunksize for the file must be set prior accessing mmaps

Definition at line 187 of file file-handling.c.

References lumiera_file_mmapings(), lumiera_mmapings_mmap_acquire(), and TRACE().

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void lumiera_file_release_mmap ( LumieraFile  self,
LumieraMMap  map 
)

release a previously acquired MMap object

Parameters
selffile to which the map belongs
mapobject to be released

Definition at line 195 of file file-handling.c.

References lumiera_file_mmapings(), lumiera_mmapings_release_mmap(), and TRACE().

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

LumieraMMapings lumiera_file_mmapings ( LumieraFile  self)

Query the underlying mmapings object from a file The MMapings only exists after a chunksize got set with lumiera_file_chunksize_set()

Parameters
selfthe file to query
Returns
Handle to the MMapings object or NULL on error (setting the error state)

Definition at line 170 of file file-handling.c.

References LUMIERA_ERROR_SET, and lumiera_filedescriptor_name().

Referenced by lumiera_file_mmap_acquire(), lumiera_file_release_mmap(), and TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int lumiera_file_checkflags ( LumieraFile  self,
int  flags 
)

Query the flags effective for a file.

Parameters
selfthe file to query
Returns
flags

Definition at line 180 of file file-handling.c.

Referenced by lumiera_fileheader_create().

+ Here is the caller graph for this function:

size_t lumiera_file_set_chunksize_bias ( LumieraFile  self,
size_t  chunksize,
size_t  bias 
)

Set the chunksize for mapping operations can only set once for a file descriptor, subsequent calls are no-ops.

Parameters
chunksizeallocation/mmaping granularity, must be 2's exponent of page size
biasoffset to shift chunks, used for stepping over a header for example.
Returns
the effective chunksize used for the file

Definition at line 134 of file file-handling.c.

References lumiera_mmapings_new().

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

size_t lumiera_file_chunksize_get ( LumieraFile  self)

Get the chunksize for mapping operations.

Returns
the effective chunksize used for the file

Definition at line 144 of file file-handling.c.

References LUMIERA_ERROR_SET, and lumiera_filedescriptor_name().

Referenced by lumiera_mmap_init().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

size_t lumiera_file_bias_get ( LumieraFile  self)

Get the bias for mapping operations.

Returns
the effective bias used for the file

Definition at line 157 of file file-handling.c.

References LUMIERA_ERROR_SET, and lumiera_filedescriptor_name().

Referenced by lumiera_mmap_init().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

LumieraFile lumiera_file_rdlock ( LumieraFile  self)

Place and remove locks on a file.

This locks are per thread and lock the file across multiple lumiera processes (or any other program which respect to advisory file locking). Only exclusive locks over the whole file are supported for initially accessing a file, other locking is done somewhere else.

Definition at line 204 of file file-handling.c.

References lumiera_filedescriptor_rdlock(), and NULL.

+ Here is the call graph for this function:

LumieraFile lumiera_file_wrlock ( LumieraFile  self)

Definition at line 214 of file file-handling.c.

References lumiera_filedescriptor_wrlock(), and NULL.

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

LumieraFile lumiera_file_unlock ( LumieraFile  self)

Definition at line 224 of file file-handling.c.

References lumiera_filedescriptor_unlock(), and NULL.

Referenced by TEST().

+ Here is the call graph for this function:

+ Here is the caller graph for this function: