proland::TileCache Class Reference
[producer]

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

#include <TileCache.h>

List of all members.

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< TileStoragegetStorage ()
 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.
TilefindTile (int producerId, int level, int tx, int ty, bool includeCache=false)
 Looks for a tile in this TileCache.
TilegetTile (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< TileStoragestorage
 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

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.

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.

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

The producers that use this TileCache.

Maps local producer identifiers to actual producers.

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.

The storage to store the tiles data.

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).

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

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.


Generated on Sat May 12 09:41:38 2012 for proland by  doxygen 1.6.1