proland::TileCache Class Reference
[producer]

A cache of tiles to avoid recomputing recently produced tiles. More...

#include <TileCache.h>

Classes
class	Tile
	A tile described by its level,tx,ty coordinates. More...
Public Member Functions
	TileCache (ptr< TileStorage > storage, std::string name, ptr< Scheduler > scheduler=NULL)
	Creates a new TileCache.
virtual	~TileCache ()
	Deletes this TileCache.
ptr< TileStorage >	getStorage ()
	Returns the storage used to store the actual tiles data.
ptr< Scheduler >	getScheduler ()
	Returns the scheduler used to schedule prefetched tiles creation tasks.
int	getUsedTiles ()
	Returns the number of tiles currently in use in this cache.
int	getUnusedTiles ()
	Returns the number of tiles currently unused in this cache.
Tile *	findTile (int producerId, int level, int tx, int ty, bool includeCache=false)
	Looks for a tile in this TileCache.
Tile *	getTile (int producerId, int level, int tx, int ty, unsigned int deadline, int *users=NULL)
	Returns the requested tile, creating it if necessary.
ptr< Task >	prefetchTile (int producerId, int level, int tx, int ty)
	Returns a prefetch task to create the given tile.
int	putTile (Tile *t)
	Decrements the number of users of this tile by one.
void	invalidateTiles (int producerId)
	Invalidates the tiles from this cache produced by the given producer.
void	invalidateTile (int producerId, int level, int tx, int ty)
	Invalidates the selected tile from this cache produced by the given producer.
Protected Member Functions
	TileCache ()
	Creates a new uninitalized TileCache.
void	init (ptr< TileStorage > storage, std::string name, ptr< Scheduler > scheduler=NULL)
	Initializes this TileCache.
Protected Attributes
std::string	name
	The name of this cache for debugging purpose.
Private Member Functions
void	createTileTaskDeleted (int producerId, int level, int tx, int ty)
	Notifies this TileCache that a tile creation task has been deleted.
Private Attributes
int	nextProducerId
	Next local identifier to be used for a TileProducer using this cache.
map< int, TileProducer * >	producers
	The producers that use this TileCache.
ptr< TileStorage >	storage
	The storage to store the tiles data.
ptr< Scheduler >	scheduler
	The scheduler to schedule prefetched tiles creation tasks, and to reschedule invalidated tiles creation tasks.
map< Tile::TId, Tile * >	usedTiles
	The tiles currently in use.
Cache	unusedTiles
	The unused tiles.
list< Tile * >	unusedTilesOrder
	The unused tiles, ordered by date of last use (to implement a LRU cache).
map< Tile::TId, Task * >	deletedTiles
	The tasks to produce the data of deleted tiles.
int	queries
	The number of queries to this tile cache.
int	misses
	The number of missed queries to this tile cache.
void *	mutex
	A mutex to serialize parallel accesses to this cache.

Detailed Description

A cache of tiles to avoid recomputing recently produced tiles.

A tile cache keeps track of which tiles (identified by their level,tx,ty coordinates) are currently stored in an associated TileStorage. It also keeps track of which tiles are in use, and which are not. Unused tiles are kept in the TileStorage as long as possible, in order to avoid re creating them if they become needed again. But the storage associated with unused tiles can be reused to store other tiles at any moment (in this case we say that a tile is evicted from the cache of unused tiles). Conversely, the storage associated with tiles currently in use cannot be reaffected until these tiles become unused. A tile is in use when it is returned by getTile, and becomes unused when putTile is called (more precisely when the number of users of this tile becomes 0, this number being incremented and decremented by getTile and putTile, respectively). The tiles that are needed to render the current frame should be declared in use, so that they are not evicted between their creation and their actual rendering.

Authors:: Eric Bruneton, Antoine Begault, Guillaume Piolat

Constructor & Destructor Documentation

proland::TileCache::TileCache	(	ptr< TileStorage >	storage,
		std::string	name,
		ptr< Scheduler >	scheduler = `NULL`
	)

Creates a new TileCache.

Parameters:

	storage	the tile storage to store the actual tiles data.
	name	name of this cache, for logging.
	scheduler	an optional scheduler to schedule the creation of prefetched tiles. If no scheduler is specified, prefetch is disabled.

virtual proland::TileCache::~TileCache ( ) [virtual]

Deletes this TileCache.

proland::TileCache::TileCache ( ) [protected]

Creates a new uninitalized TileCache.

Member Function Documentation

void proland::TileCache::createTileTaskDeleted	(	int	producerId,
		int	level,
		int	tx,
		int	ty
	)			`[private]`

Notifies this TileCache that a tile creation task has been deleted.

Tile* proland::TileCache::findTile	(	int	producerId,
		int	level,
		int	tx,
		int	ty,
		bool	includeCache = `false`
	)

Looks for a tile in this TileCache.

Parameters:

	producerId	the id of the tile's producer.
	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	includeCache	true to include both used and unused tiles in the search, false to include only the used tiles.

Returns:: the requested tile, or NULL if it is not in this TileCache. This method does not change the number of users of the returned tile.

ptr<Scheduler> proland::TileCache::getScheduler ( )

Returns the scheduler used to schedule prefetched tiles creation tasks.

ptr<TileStorage> proland::TileCache::getStorage ( )

Returns the storage used to store the actual tiles data.

Tile* proland::TileCache::getTile	(	int	producerId,
		int	level,
		int	tx,
		int	ty,
		unsigned int	deadline,
		int *	users = `NULL`
	)

Returns the requested tile, creating it if necessary.

If the tile is currently in use it is returned directly. If it is in cache but unused, it marked as used and returned. Otherwise a new tile is created, marked as used and returned. In all cases the number of users of this tile is incremented by one.

Parameters:

	producerId	the id of the tile's producer.
	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	deadline	the deadline at which the tile data must be ready. 0 means the current frame.
`[out]`	the	number of users of this tile, before it is incremented.

Returns:: the requested tile, or NULL if there is no room left in the TileStorage to store the requested tile.

int proland::TileCache::getUnusedTiles ( )

Returns the number of tiles currently unused in this cache.

int proland::TileCache::getUsedTiles ( )

Returns the number of tiles currently in use in this cache.

void proland::TileCache::init	(	ptr< TileStorage >	storage,
		std::string	name,
		ptr< Scheduler >	scheduler = `NULL`
	)			`[protected]`

Initializes this TileCache.

Parameters:

	storage	the tile storage to store the actual tiles data.
	name	name of this cache, for logging.
	scheduler	an optional scheduler to schedule the creation of prefetched tiles. If no scheduler is specified, prefetch is disabled.

void proland::TileCache::invalidateTile	(	int	producerId,
		int	level,
		int	tx,
		int	ty
	)

Invalidates the selected tile from this cache produced by the given producer.

This means that the tasks to produce the actual data of this tile will be automatically reexecuted before the data can be used.

Parameters:

	producerId	the id of a producer using this cache. See TileProducer::getId.
	level	the level of a tile in the producer
	tx	the x coord of that tile
	ty	the y coord of that tile

void proland::TileCache::invalidateTiles ( int producerId )

Invalidates the tiles from this cache produced by the given producer.

This means that the tasks to produce the actual data of these tiles will be automatically reexecuted before the data can be used.

Parameters:

producerId

the id of a producer using this cache. See TileProducer::getId.

ptr<Task> proland::TileCache::prefetchTile	(	int	producerId,
		int	level,
		int	tx,
		int	ty
	)

Returns a prefetch task to create the given tile.

If the requested tile is currently in use or in cache but unused, this method does nothing. Otherwise it gets an unused tile storage (evicting an unused tile if necessary), and then creates a task to produce the data of the requested tile, in this storage. This method must not be called if getScheduler returns NULL.

Parameters:

	producerId	the id of the tile's producer.
	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.

int proland::TileCache::putTile ( Tile * t )

Decrements the number of users of this tile by one.

If this number becomes 0 the tile is marked as unused, and so can be evicted from the cache at any moment.

Parameters:

t

a tile currently in use.

Returns:: the number of users of this tile, after it has been decremented.

Member Data Documentation

map<Tile::TId, Task*> proland::TileCache::deletedTiles [private]

The tasks to produce the data of deleted tiles.

When an unused tile is evicted from the cache it is destroyed, but its producer task may not be destroyed (if there remain some reference to it, for example via a task graph). If the tile is needed again, getTile will create a new Tile, which could produce a new producer task. Hence we could get two producer tasks for the same tile, which could lead to inconsistencies (the two tasks may not have the same execution state, may not use the same storage to store their result, etc). To avoid this problem we store the tasks of deleted tiles in this map, in order to reuse them if a deleted tile is needed again. When a producer task gets deleted, it removes itself from this map by calling createTileTaskDeleted (because then it is not a problem to recreate a new Task, there will be no duplication). So the size of this map cannot grow unbounded.

int proland::TileCache::misses [private]

The number of missed queries to this tile cache.

This is the number of times a tile was requested but not found in the cache, requiring to (re)create it. Only used for statistics.

void* proland::TileCache::mutex [private]

A mutex to serialize parallel accesses to this cache.

std::string proland::TileCache::name [protected]

The name of this cache for debugging purpose.

int proland::TileCache::nextProducerId [private]

Next local identifier to be used for a TileProducer using this cache.

map<int, TileProducer*> proland::TileCache::producers [private]

The producers that use this TileCache.

Maps local producer identifiers to actual producers.

int proland::TileCache::queries [private]

The number of queries to this tile cache.

Only used for statistics.

ptr<Scheduler> proland::TileCache::scheduler [private]

The scheduler to schedule prefetched tiles creation tasks, and to reschedule invalidated tiles creation tasks.

ptr<TileStorage> proland::TileCache::storage [private]

The storage to store the tiles data.

Cache proland::TileCache::unusedTiles [private]

The unused tiles.

These tiles can be evicted from the cache at any moment. Maps tile identifiers to positions in the ordered list of tiles unusedTilesOrder (used to implement a LRU cache).

list<Tile*> proland::TileCache::unusedTilesOrder [private]

The unused tiles, ordered by date of last use (to implement a LRU cache).

map<Tile::TId, Tile*> proland::TileCache::usedTiles [private]

The tiles currently in use.

These tiles cannot be evicted from the cache and from the TileStorage, until they become unused. Maps tile identifiers to actual tiles.

proland::TileCache Class Reference [producer]

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

proland::TileCache Class Reference
[producer]