All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | List of all members
kjb::TopoFusion::Tile_manager Class Reference

RAII tool for opening and closing the DOQ master index. More...

#include <dorthoquad.h>

Public Member Functions

 Tile_manager (const char *dir=IVILAB_DOQ_TILE_CACHE_DIRECTORY)
 Open the tile cache index, if possible on the IVI lab fileserver. More...
 ~Tile_manager ()
 dtor closes the tile cache index, maybe deleting the index. More...
bool is_using_a_temporary_cache () const
 returns whether the cache is stored in a temporary directory. More...

Static Public Member Functions

static bool is_already_instantiated_elsewhere ()
 return whether the (singleton) object already exists More...

Detailed Description

RAII tool for opening and closing the DOQ master index.

This object manages the DOQ master index of tile files, which should be opened prior to generating a DOQ, and closed when it is no longer needed. DOQ tiles are available two places: from msrmaps.com and from the local cache stored on an IVI Lab fileserver, specifically the one called "data_3."

The data_3 fileserver is only visible inside the IVI lab network. If you are attached to the network (by wire or by SSH tunnel) then you will probably get fastest response using our fileserver. Any locations absent from the fileserver will be downloaded from the internet and stored in the fileserver's cache. The cache size has no explicit limit, as of this writing (July 2013).

If you are outside the network (i.e., not attached via wire or SSH or any other tunnel) you can download files using the internet, provided that msrmaps.com is still serving the tiles, something they won't do forever. This will then store tiles locally, in your /tmp directory (or equivalent temporary location), and delete them when this object is destroyed. Please note that it will NOT help you build up a local cache of tiles! To repeat: unless you connect to an existing tile cache in a local filesystem, this object will delete whatever it downloads.

If you want to keep the tiles you download, then you must use the C interface directly. Specifically, call the init_master() function in a properly-prepared directory of your choice. If you do all that, you can (after you've set it up) instantiate one of these objects and point it at the top-level directory, and the object will grow the cache for you as you create DOrthoquad objects pointed hither and yon.

This class is not copyable, not assignable, and is meant to be singleton, i.e., at most one instance exists in any run. The tile index relies on statically-stored structures behind the scenes, so you cannot safely open multiple indexes if accessing a filesystem cache (neither with threads nor with separate processes). Singleton semantics is enforced: if you try to instantiate a second time in one process, the ctor will throw. You can instantiate multiple managers if they are attached to temporary caches; however, be careful not to stress out msrmaps.com.

msrmaps.com is a free service but their goodwill cannot possibly be unlimited. If we download lots of tiles from them, we could exhaust their generosity of bandwidth.

Constructor & Destructor Documentation

kjb::TopoFusion::Tile_manager::Tile_manager ( const char *  dir = IVILAB_DOQ_TILE_CACHE_DIRECTORY)

Open the tile cache index, if possible on the IVI lab fileserver.

dirOPTIONAL pathname to tile cache. Usually omitted; see below.
KJB_errorif we cannot initialize (and lots of steps can fail).

In typical use, you should NOT supply a dir argument; instead, you should accept the default. The default will test whether the files we want are already available on the local filesystem, in the "usual place." On an IVI lab machine, the "usual place" will indeed hold tile files. If "the usual place" does not even exist, nothing bad happens! Instead, we create a temporary directory for tile files, and download them from msrmaps.com. We will delete the temporary directory and its contents at destructor-time.

The idea here is to make life easy for you, the caller! Ideally you need not add any logic to test whether you're on the SISTA network. This class will handle it for you. On the network we use cached tiles, off the network (hopefully a rare situation) we download them.

The only time you need to supply an argument for 'dir' is if you have (on your own) built up your own cache of tile files in TopoFusion format and you want to use that cache or expand it. If so, you should pass in the absolute pathname to the directory that contains the files mapindex.dat file and the maps.dat subdirectory. Caches of this kind easily grow to a few gigabytes. This class will not help you get it started, but if you've already gotten started this class could help you grow it.

kjb::TopoFusion::Tile_manager::~Tile_manager ( )

dtor closes the tile cache index, maybe deleting the index.

Member Function Documentation

static bool kjb::TopoFusion::Tile_manager::is_already_instantiated_elsewhere ( )

return whether the (singleton) object already exists

bool kjb::TopoFusion::Tile_manager::is_using_a_temporary_cache ( ) const

returns whether the cache is stored in a temporary directory.

The documentation for this class was generated from the following files: