TableCache.h

Go to the documentation of this file.

// # TableCache.h: Cache of open tables
// # Copyright (C) 1994,1995,1997,1999
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef TABLES_TABLECACHE_H
#define TABLES_TABLECACHE_H
 
// # Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/ArrayFwd.h>
#include <casacore/casa/IO/FileLocker.h>
 
#include <map>
#include <mutex>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// # Forward Declarations
class PlainTable;
class TableLock;
 
// <summary>
// Cache of open tables
// </summary>
 
// <use visibility=local>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
// </reviewed>
 
// <prerequisite>
// # Classes you should understand before using this one.
// </prerequisite>
 
// <etymology>
// TableCache represents a cache of open tables.
// </etymology>
 
// <synopsis>
// A TableCache object keeps track of the tables which have already
// been opened in a program. It maps the name of a table to its
// PlainTable object.
// In principle only one TableCache object (statically defined in
// class PlainTable) exists in a process.
// The cache is used to prevent a table from being opened more than
// once, which is not only a waste of space, but more importantly,
// may give rise to synchronization problems.
// Synchronization between the same table in multiple processes must
// be done by a locking mechanism.
//
// TableCache is used by class Table and PlainTable.
// Before opening a table, Table will first look in the cache.
// Newly opened or created tables will be added to the cache.
// When a table is actually closed, it will be removed from the cache.
// </synopsis>
 
// <motivation>
// When a RefTable is read back, it will also read back the table it
// references. However, that table may have been opened before and
// it is bad to have a table open more than once in the same program.
// The TableCache class catches this and will not reopen the table.
// </motivation>
 
// <todo asof="$DATE:$">
// # A List of bugs, limitations, extensions or planned refinements.
//   <li> Currently only PlainTables are taken into account.
//          Maybe RefTables should be too.
// </todo>
 
class TableCache {
 public:
  // Construct an empty cache of open tables.
  TableCache();
 
  ~TableCache();
 
  // The copy constructor is forbidden.
  TableCache(const TableCache&) = delete;
 
  // The assignment operator is forbidden.
  TableCache& operator=(const TableCache&) = delete;
 
  // Try to find a table with the given name in the cache.
  // Return a pointer to a table if found (thus if already open).
  // Return a zero pointer if not found.
  PlainTable* operator()(const String& tableName) const;
 
  // Add an open table to the cache.
  void define(const String& tableName, PlainTable*);
 
  // Remove an open table.
  void remove(const String& tableName);
 
  // Rename an open table.
  // If oldName is not in the cache, nothing will be done.
  void rename(const String& newName, const String& oldName);
 
  // Determine the number of locked tables opened with the AutoLock option
  // (Locked table means locked for read and/or write).
  uInt nAutoLocks();
 
  // Unlock locked tables opened with the AutoLock option.
  // If <src>all=True</src> all such tables will be unlocked.
  // If <src>all=False</src> only tables requested by another process
  // will be unlocked.
  void relinquishAutoLocks(Bool all);
 
  // Get the names of the tables in the cache.
  Vector<String> getTableNames() const;
 
  // Get the names of tables locked in this process.
  // By default all locked tables are given (note that a write lock
  // implies a read lock), but it is possible to select on lock type
  // FileLocker::Write and on option (TableLock::AutoLocking,
  // TableLock::ReadLocking, or TableLock::PermanentLocking).
  Vector<String> getLockedTables(FileLocker::LockType, int lockOption);
 
  // Flush a possibly cached Table.
  void flushTable(const String& tableName, Bool fsync, Bool recursive);
 
  // Look in the cache if the table is already open.
  // If so, check if table option matches.
  // If needed reopen the table for read/write and merge the lock options.
  PlainTable* lookCache(const String& name, int tableOption, const TableLock& tableInfo);
 
 private:
  // Get the table without doing a mutex lock (for operator()).
  PlainTable* getTable(const String& tableName) const;
 
  // # void* iso. PlainTable* is used in the map declaration
  // # to reduce the number of template instantiations.
  // # The .cc file will use (fully safe) casts.
  std::map<String, void*> tableMap_p;
  // # A mutex to synchronize access to the cache.
  mutable std::mutex itsMutex;
};
 
}  // namespace casacore
 
#endif