gp_dir_cache.h File Reference

A cache for a directory content. More...

#include <utils/gp_poll.h>
#include <time.h>

Go to the source code of this file.

Data Structures
struct	gp_dir_entry
	A dir cache entry, represents a file or a directory. More...
struct	gp_dir_cache
	A directory cache. More...

Typedefs
typedef struct gp_dir_entry	gp_dir_entry
	A dir cache entry, represents a file or a directory.
typedef enum gp_dir_cache_sort_type	gp_dir_cache_sort_type
	How should be the listing sorted.
typedef struct gp_dir_cache	gp_dir_cache
	A directory cache.

Enumerations
enum	gp_dir_cache_sort_type {   GP_DIR_SORT_ASC = 0x00 , GP_DIR_SORT_DESC = 0x04 , GP_DIR_SORT_BY_NAME = 0x00 , GP_DIR_SORT_BY_SIZE = 0x01 ,   GP_DIR_SORT_BY_MTIME = 0x02 }
	How should be the listing sorted. More...
enum	gp_dir_cache_type { GP_DIR_CACHE_NONE = 0 , GP_DIR_CACHE_FILE = 1 , GP_DIR_CACHE_DIR = 2 }
	A cache entry lookup type. More...

Functions
gp_dir_cache *	gp_dir_cache_new (const char *path)
	Creates and populates a new directory cache.
void	gp_dir_cache_destroy (gp_dir_cache *self)
	Destroys a directory cache.
gp_dir_entry *	gp_dir_cache_add_entry (gp_dir_cache *self, size_t size, const char *name, mode_t mode, time_t mtime)
	Adds an entry to the directory cache.
int	gp_dir_cache_rem_entry_by_name (gp_dir_cache *self, const char *name)
	Removes an entry from directory cache.
gp_dir_entry *	gp_dir_cache_entry_lookup (gp_dir_cache *self, const char *name)
	Looks up an entry based on a file name.
int	gp_dir_cache_entry_name_contains (gp_dir_cache *self, const char *needle)
	Returns true if there is at least one entry with needle in the name.
void	gp_dir_cache_free_entries (gp_dir_cache *self)
	Frees all entries from directory cache.
void	gp_dir_cache_sort (gp_dir_cache *self, gp_dir_cache_sort_type sort_type)
	Sorts the directory cache entries.
static gp_dir_entry *	gp_dir_cache_get (gp_dir_cache *self, unsigned int pos)
	Returns an entry given a position.
static void	gp_dir_cache_set_filter (gp_dir_cache *self, unsigned int pos, int filter)
	Sets dir cache entry filter flag.
static size_t	gp_dir_cache_entries (gp_dir_cache *self)
	Returns number of entries.
static size_t	gp_dir_cache_entries_filter (gp_dir_cache *self)
	Returns number of not-filtered entries.
gp_dir_entry *	gp_dir_cache_get_filtered (gp_dir_cache *self, unsigned int pos)
	Returns entry on position pos ignoring filtered out elements.
int	gp_dir_cache_notify (gp_dir_cache *self)
	A change notify handler.
gp_fd *	gp_dir_cache_notify_fd (gp_dir_cache *self)
	Returns inotify fd if available.
int	gp_dir_cache_mkdir (gp_dir_cache *self, const char *dirname)
	Creates a directory and updates the cache.
unsigned int	gp_dir_cache_pos_by_name_filtered (gp_dir_cache *self, const char *name)
	Looks up a entry position by name.
enum gp_dir_cache_type	gp_dir_cache_lookup (gp_dir_cache *self, const char *name)
	Looks for a file in the directory the cache operates in.

Detailed Description

A cache for a directory content.

This implements an data structure to cache a directory content so that it can be listed in an alphabetical order. It also listens for a inotify events so the list is updated whenever the directory content changes.

Definition in file gp_dir_cache.h.

Enumeration Type Documentation

gp_dir_cache_sort_type

enum gp_dir_cache_sort_type

How should be the listing sorted.

Enumerator
GP_DIR_SORT_ASC	Sort in an ascending order.
GP_DIR_SORT_DESC	Sort in a descending order.
GP_DIR_SORT_BY_NAME	Sort by name.
GP_DIR_SORT_BY_SIZE	Sort by size.
GP_DIR_SORT_BY_MTIME	Sort by modification time.

Definition at line 41 of file gp_dir_cache.h.

gp_dir_cache_type

enum gp_dir_cache_type

A cache entry lookup type.

Enumerator
GP_DIR_CACHE_NONE	No element found.
GP_DIR_CACHE_FILE	File type element found.
GP_DIR_CACHE_DIR	A directory type element found.

Definition at line 275 of file gp_dir_cache.h.

Function Documentation

gp_dir_cache_add_entry()

gp_dir_entry * gp_dir_cache_add_entry	(	gp_dir_cache *	self,
		size_t	size,
		const char *	name,
		mode_t	mode,
		time_t	mtime
	)

Adds an entry to the directory cache.

This function is called by the platform code.

Parameters

self	A directory cache to add the entry to
size	A file size in bytes
name	A file name
mode	A file mode
mtime	A modification timestamp

Returns

A pointer to a newly allocated directory entry.

gp_dir_cache_destroy()

void gp_dir_cache_destroy

(

gp_dir_cache *

self

)

Destroys a directory cache.

Closes all file descriptors, frees memory.

Parameters

self	A directory cache to destroy.

gp_dir_cache_entries()

static size_t gp_dir_cache_entries ( gp_dir_cache *  self )

inlinestatic

Returns number of entries.

Parameters

self	A directory cache.

Returns

A number of entries.

Definition at line 202 of file gp_dir_cache.h.

References gp_dir_cache::used.

gp_dir_cache_entries_filter()

static size_t gp_dir_cache_entries_filter ( gp_dir_cache *  self )

inlinestatic

Returns number of not-filtered entries.

Parameters

self	A directory cache.

Returns

A number of entries.

Definition at line 214 of file gp_dir_cache.h.

References gp_dir_cache::filtered, and gp_dir_cache::used.

gp_dir_cache_entry_lookup()

gp_dir_entry * gp_dir_cache_entry_lookup	(	gp_dir_cache *	self,
		const char *	name
	)

Looks up an entry based on a file name.

Parameters

self	A directory cache.
name	An entry name to look for.

Returns

An directory entry on NULL if there is no such entry

gp_dir_cache_entry_name_contains()

int gp_dir_cache_entry_name_contains	(	gp_dir_cache *	self,
		const char *	needle
	)

Returns true if there is at least one entry with needle in the name.

Parameters

self	A directory cache.
needle	A (sub)string in the name to look for.

Returns

Non-zero if entry with needle in name exists zero otherwise.

gp_dir_cache_free_entries()

void gp_dir_cache_free_entries

(

gp_dir_cache *

self

)

Frees all entries from directory cache.

This function is called by the platform code.

Parameters

self	A directory cache.

gp_dir_cache_get()

static gp_dir_entry * gp_dir_cache_get ( gp_dir_cache *  self, unsigned int  pos  )

inlinestatic

Returns an entry given a position.

Parameters

self	A directory cache.
pos	Element position in the gp_dir_cache::entries array.

Returns

A pointer to an entry or NULL if pos is outside of the array.

Definition at line 166 of file gp_dir_cache.h.

References gp_dir_cache::entries, and gp_dir_cache::used.

gp_dir_cache_get_filtered()

gp_dir_entry * gp_dir_cache_get_filtered	(	gp_dir_cache *	self,
		unsigned int	pos
	)

Returns entry on position pos ignoring filtered out elements.

Parameters

self	A directory cache.
pos	Element position in the gp_dir_cache::entries array.

Returns

A dir cache entry or NULL if position is not occupied.

gp_dir_cache_lookup()

enum gp_dir_cache_type gp_dir_cache_lookup	(	gp_dir_cache *	self,
		const char *	name
	)

Looks for a file in the directory the cache operates in.

Parameters

self	A dir cache.
name	A filename.

Returns

An entry type, returns GP_DIR_CACHE_NONE if element with such name wasn't found.

gp_dir_cache_mkdir()

int gp_dir_cache_mkdir	(	gp_dir_cache *	self,
		const char *	dirname
	)

Creates a directory and updates the cache.

Parameters

self	A dir cache.
dirname	A directory name.

Returns

Returns an errno on a failure.

gp_dir_cache_new()

gp_dir_cache * gp_dir_cache_new

(

const char *

path

)

Creates and populates a new directory cache.

Creates a directory cache and fills it with list of entries at the given path. If supported the directory is also set up to with an inotify watch in order to update the listing whenever the directory content changes.

Parameters

path	A path to load the cache entries from.

Returns

Newly allocated and populated directory cache or NULL in case of allocation failure.

gp_dir_cache_notify()

int gp_dir_cache_notify

(

gp_dir_cache *

self

)

A change notify handler.

This function should be called to update the cache content when there are data to be read on inotify fd.

Parameters

self	A directory cache.

Returns

Returns non-zero if cache content changed.

gp_dir_cache_notify_fd()

gp_fd * gp_dir_cache_notify_fd

(

gp_dir_cache *

self

)

Returns inotify fd if available.

Parameters

self	A direcotry cache.

Returns

A file descriptor structure for gp_poll().

gp_dir_cache_pos_by_name_filtered()

unsigned int gp_dir_cache_pos_by_name_filtered	(	gp_dir_cache *	self,
		const char *	name
	)

Looks up a entry position by name.

Warning

Looks up for a file in the cache and returns an position. Note that the position is not stable and will change on sort or when notify events are processed.

Parameters

self	A dir cache.
name	A directory or file name.

Returns

A position in the gp_dir_cache::entries array.

gp_dir_cache_rem_entry_by_name()

int gp_dir_cache_rem_entry_by_name	(	gp_dir_cache *	self,
		const char *	name
	)

Removes an entry from directory cache.

This function is called by the platform code.

Parameters

self	A directory cache to remove the entry from
name	An entry name to be removed

Returns

Zero on success i.e. entry was found, non-zero otherwise.

gp_dir_cache_set_filter()

static void gp_dir_cache_set_filter ( gp_dir_cache *  self, unsigned int  pos, int  filter  )

inlinestatic

Sets dir cache entry filter flag.

If element has been set to be filtered it's ignored by functions with the _filter suffix.

Parameters

self	A directory cache.
pos	Element position in the gp_dir_cache::entries array.
filter	Either 1 == filtered or 0 == not filtered.

Definition at line 185 of file gp_dir_cache.h.

References gp_dir_cache::entries, gp_dir_entry::filtered, and gp_dir_cache::filtered.

gp_dir_cache_sort()

void gp_dir_cache_sort	(	gp_dir_cache *	self,
		gp_dir_cache_sort_type	sort_type
	)

Sorts the directory cache entries.

Parameters

self	A directory cache.
sort_type	A requested sort order.