bdlt_timetablecache.h

Go to the documentation of this file.

/// @file bdlt_timetablecache.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlt_timetablecache.h                                              -*-C++-*-
#ifndef INCLUDED_BDLT_TIMETABLECACHE
#define INCLUDED_BDLT_TIMETABLECACHE
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdlt_timetablecache bdlt_timetablecache
/// @brief  Provide an efficient cache for read-only `bdlt::Timetable` objects.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlt
/// @{
/// @addtogroup bdlt_timetablecache
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlt_timetablecache-purpose"> Purpose</a>
/// * <a href="#bdlt_timetablecache-classes"> Classes </a>
/// * <a href="#bdlt_timetablecache-description"> Description </a>
///   * <a href="#bdlt_timetablecache-thread-safety"> Thread Safety </a>
///   * <a href="#bdlt_timetablecache-usage"> Usage </a>
///     * <a href="#bdlt_timetablecache-example-1-using-a-bdlt-timetablecache"> Example 1: Using a bdlt::TimetableCache </a>
///     * <a href="#bdlt_timetablecache-example-2-a-timetable-cache-with-a-timeout"> Example 2: A Timetable Cache with a Timeout </a>
///
/// # Purpose {#bdlt_timetablecache-purpose}
/// Provide an efficient cache for read-only `bdlt::Timetable` objects.
///
/// # Classes {#bdlt_timetablecache-classes}
///
/// - bdlt::TimetableCache: cache for read-only timetables loaded on demand
///
/// @see  bdlt_timetable, bdlt_timetableloader
///
/// # Description {#bdlt_timetablecache-description}
/// This component defines the `bdlt::TimetableCache` class, a
/// cache for read-only `bdlt::Timetable` objects.  The `bdlt::TimetableCache`
/// class defines two methods for fetching timetables from the cache: a
/// manipulator called `getTimetable` and an accessor called `lookupTimetable`.
/// Timetables are identified by name using C-style strings, and both retrieval
/// methods return a `bsl::shared_ptr<const bdlt::Timetable>`.
///
/// The first time a timetable is requested from the cache using the
/// `getTimetable` manipulator, the identified timetable is loaded into the
/// cache using the loader that was supplied upon construction of the cache (see
/// @ref bdlt_timetableloader ); a reference to that newly-loaded timetable is then
/// returned.  Subsequent requests for the same timetable, using either the
/// `getTimetable` or `lookupTimetable` method, are efficiently satisfied by
/// returning references to the cached instance.  The `lookupTimetable` accessor
/// differs from the `getTimetable` manipulator in that when a request is made
/// through the accessor for a timetable that is *not* present in the cache, the
/// timetable is not loaded as a side-effect.  In this case, an empty
/// `bsl::shared_ptr<const bdlt::Timetable>` is returned instead, which is
/// effectively a null pointer.  Note that the timetable-naming convention in
/// effect for a given cache is determined by the concrete loader supplied at
/// construction of the cache.
///
/// Timetables stored in a cache can be explicitly invalidated; the `invalidate`
/// method is used to invalidate a single timetable and `invalidateAll`
/// invalidates all timetables in the cache.  Invalidated timetables are removed
/// from the cache.  However, a timetable that has been invalidated in the cache
/// remains valid to all outstanding references to it, obtained via earlier
/// calls to the `getTimetable` and `lookupTimetable` methods, until all of
/// those references have been destroyed.  Note that a subsequent request, using
/// the `getTimetable` manipulator, for a timetable that has been invalidated
/// incurs the overhead of once again loading that timetable into the cache.
///
/// Timetables can also be invalidated on the basis of a timeout.  To use this
/// feature of `bdlt::TimetableCache`, a `bsls::TimeInterval` timeout must be
/// supplied at construction.  When a timeout is in effect for a cache, requests
/// for a timetable from the cache using the `getTimetable` manipulator may
/// incur the reloading of the timetable if the one in the cache has expired
/// (i.e., the time interval defined by the timeout value has elapsed since the
/// timetable was last loaded).  In the case of the `lookupTimetable` accessor,
/// an empty `bsl::shared_ptr<const bdlt::Timetable>` is returned if the
/// requested timetable is found to have expired.
///
/// ## Thread Safety {#bdlt_timetablecache-thread-safety}
///
///
/// The `bdlt::TimetableCache` class is fully thread-safe (see
/// @ref bsldoc_glossary ) provided that the allocator supplied at construction and
/// the default allocator in effect during the lifetime of cache objects are
/// both fully thread-safe.
///
/// ## Usage {#bdlt_timetablecache-usage}
///
///
/// The following example illustrates how to use a `bdlt::TimetableCache`.
///
/// ### Example 1: Using a bdlt::TimetableCache {#bdlt_timetablecache-example-1-using-a-bdlt-timetablecache}
///
///
/// This example shows basic use of a `bdlt::TimetableCache` object.
///
/// In this example, we assume a hypothetical timetable loader,
/// `MyTimetableLoader`, the details of which are not important other than that
/// it supports timetables identified by "ZERO", "ONE", and "TWO".  Furthermore,
/// the value of the initial transition code for each of these timetables is
/// given by the timetable's name (e.g., if `Z` has the value of the timetable
/// identified as "ZERO", then `0 == Z.initialTransitionCode()`).
///
/// First, we create a timetable loader, an instance of `MyTimetableLoader`, and
/// use it, in turn, to create a cache.  For the purposes of this example, it is
/// sufficient to let the cache use the default allocator:
/// @code
/// MyTimetableLoader    loader;
/// bdlt::TimetableCache cache(&loader);
/// @endcode
/// Next, we retrieve the timetable `twoA`, identified by "TWO", verify that the
/// loading of that timetable into the cache was successful (`twoA.get()` is
/// non-null), and verify that 2 is the value of the initial transition code for
/// timetable "TWO":
/// @code
/// bsl::shared_ptr<const bdlt::Timetable> twoA = cache.getTimetable("TWO");
///
/// assert(twoA.get());
/// assert(2 == twoA->initialTransitionCode());
/// @endcode
/// Then, we fetch the timetable identified by "ONE", this time verifying that 1
/// is the value of the initial transition code for the "ONE" timetable:
/// @code
/// bsl::shared_ptr<const bdlt::Timetable> oneA = cache.getTimetable("ONE");
///
/// assert(oneA.get());
/// assert(1 == oneA->initialTransitionCode());
/// @endcode
/// Next, we retrieve the "ONE" timetable again, this time via the
/// `lookupTimetable` accessor, and note that the request is satisfied by the
/// timetable that is already in the cache:
/// @code
/// const bdlt::TimetableCache& readonlyCache = cache;
///
/// bsl::shared_ptr<const bdlt::Timetable> oneB =
///                                       readonlyCache.lookupTimetable("ONE");
///
/// assert(oneA.get() == oneB.get());
/// @endcode
/// Then, we invalidate the "TWO" timetable in the cache and immediately fetch
/// it again.  The call to `invalidate` removed the "TWO" timetable from the
/// cache, so it had to be reloaded into the cache to satisfy the request:
/// @code
/// int numInvalidated = cache.invalidate("TWO");
/// assert(1 == numInvalidated);
///
/// bsl::shared_ptr<const bdlt::Timetable> twoB = cache.getTimetable("TWO");
///
/// assert(twoB.get() != twoA.get());
/// assert(twoB.get());
/// assert(2 == twoB->initialTransitionCode());
/// @endcode
/// Next, all timetables in the cache are invalidated, then reloaded:
/// @code
/// numInvalidated = cache.invalidateAll();
/// assert(2 == numInvalidated);
///
/// bsl::shared_ptr<const bdlt::Timetable> twoC = cache.getTimetable("TWO");
///
/// assert(twoC.get() != twoA.get());
/// assert(twoC.get() != twoB.get());
/// assert(twoC.get());
/// assert(2 == twoC->initialTransitionCode());
///
/// bsl::shared_ptr<const bdlt::Timetable> oneC = cache.getTimetable("ONE");
///
/// assert(oneC.get() != oneA.get());
/// assert(oneC.get() != oneB.get());
/// assert(oneC.get());
/// assert(1 == oneC->initialTransitionCode());
/// @endcode
/// Now, verify that references to timetables that were invalidated in the cache
/// are still valid for clients that obtained references to them before they
/// were made invalid:
/// @code
/// assert(1 == oneA->initialTransitionCode());
/// assert(1 == oneB->initialTransitionCode());
///
/// assert(2 == twoA->initialTransitionCode());
/// assert(2 == twoB->initialTransitionCode());
/// @endcode
/// When `twoA`, `twoB`, `oneA`, and `oneB` go out of scope, the resources used
/// by the timetables to which they refer are automatically reclaimed.
///
/// Finally, using the `lookupTimetable` accessor, we attempt to retrieve a
/// timetable that has not yet been loaded into the cache, but that we *know* to
/// be supported by the timetable loader.  Since the `lookupTimetable` accessor
/// does not load timetables into the cache as a side-effect, the request fails:
/// @code
/// bsl::shared_ptr<const bdlt::Timetable> zero =
///                                      readonlyCache.lookupTimetable("ZERO");
///
/// assert(!zero.get());
/// @endcode
///
/// ### Example 2: A Timetable Cache with a Timeout {#bdlt_timetablecache-example-2-a-timetable-cache-with-a-timeout}
///
///
/// This second example shows the effects on a `bdlt::TimetableCache` object
/// that is constructed to have a timeout value.  Note that the following
/// snippets of code assume a platform-independent `sleepSeconds` method that
/// sleeps for the specified number of seconds.
///
/// First, we create a timetable loader and a timetable cache.  The cache is
/// constructed to have a timeout of 3 seconds.  Of course, such a short timeout
/// is inappropriate for production use, but it is necessary for illustrating
/// the effects of a timeout in this example.  As in example 1 (above), we again
/// let the cache use the default allocator:
/// @code
/// MyTimetableLoader           loader;
/// bdlt::TimetableCache        cache(&loader, bsls::TimeInterval(3, 0));
/// const bdlt::TimetableCache& readonlyCache = cache;
/// @endcode
/// Next, we retrieve the timetable identified by "ZERO" from the cache:
/// @code
/// bsl::shared_ptr<const bdlt::Timetable> zeroA = cache.getTimetable("ZERO");
///
/// assert(zeroA.get());
/// @endcode
/// Next, we sleep for 2 seconds before retrieving the "ONE" timetable:
/// @code
/// sleepSeconds(2);
///
/// bsl::shared_ptr<const bdlt::Timetable> oneA = cache.getTimetable("ONE");
///
/// assert(oneA.get());
/// @endcode
/// Next, we sleep for 2 more seconds before attempting to retrieve the "ZERO"
/// timetable again, this time using the `lookupTimetable` accessor.  Since the
/// cumulative sleep time exceeds the timeout value established for the cache
/// when it was constructed, the "ZERO" timetable has expired; hence, it has
/// been removed from the cache:
/// @code
/// sleepSeconds(2);
///
/// bsl::shared_ptr<const bdlt::Timetable> zeroB =
///                                      readonlyCache.lookupTimetable("ZERO");
///
/// assert(!zeroB.get());
/// @endcode
/// Next, we verify that the "ONE" timetable is still available in the cache:
/// @code
/// bsl::shared_ptr<const bdlt::Timetable> oneB =
///                                       readonlyCache.lookupTimetable("ONE");
///
/// assert(oneA.get() == oneB.get());
/// @endcode
/// Finally, we sleep for an additional 2 seconds and verify that the "ONE"
/// timetable has also expired:
/// @code
/// sleepSeconds(2);
///
/// bsl::shared_ptr<const bdlt::Timetable> oneC =
///                                       readonlyCache.lookupTimetable("ONE");
///
/// assert(!oneC.get());
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlt
 * @{
 */
/** @addtogroup bdlt_timetablecache
 * @{
 */
 
#include <bdlscm_version.h>
 
#include <bdlt_timetable.h>
#include <bdlt_datetime.h>
#include <bdlt_datetimeinterval.h>
 
#include <bslma_allocator.h>
#include <bslma_usesbslmaallocator.h>
 
#include <bslmf_nestedtraitdeclaration.h>
 
#include <bslmt_mutex.h>
 
#include <bsls_timeinterval.h>
 
#include <bsl_map.h>
#include <bsl_memory.h>  // 'bsl::shared_ptr'
#include <bsl_string.h>
 
 
namespace bdlt {
 
class TimetableLoader;
class TimetableCache_Entry;
 
                        // ==========================
                        // class TimetableCache_Entry
                        // ==========================
 
// IMPLEMENTATION NOTE: The Sun Studio 12.3 compiler does not support 'map's
// holding types that are incomplete at the point of declaration of a data
// member.  Other compilers allow us to complete 'TimetableCache_Entry' at a
// later point in the code, but before any operation (such as 'insert') that
// would require the type to be complete.  If we did not have to support this
// compiler, this whole class could be defined in the .cpp file; as it stands,
// it *must* be defined before class 'TimetableCache'.
 
/// This class defines the type of objects that are inserted into the
/// timetable cache.  Each entry contains a shared pointer to a read-only timetable and the time at which that timetable was loaded.  
/// 
/// \note Note that   an
/// explicit allocator is *required* to create an entry object.
///
/// See @ref bdlt_timetablecache 
class TimetableCache_Entry {
 
    // DATA
    bsl::shared_ptr<const Timetable> d_ptr;       // shared pointer to
                                                  // out-of-place instance
 
    Datetime                         d_loadTime;  // time when timetable was
                                                  // loaded
 
  public:
    // CREATORS
 
    /// Create an empty cache entry object.  
    /// \note Note that  an empty cache entry
    /// is never actually inserted into the cache.
    TimetableCache_Entry();
 
    /// Create a cache entry object for managing the specified `timetable`
    /// that was loaded at the specified `loadTime` using the specified `allocator`.  
    /// 
    /// \pre The behavior is undefined   unless `timetable` uses
    /// `allocator` to obtain memory.
    TimetableCache_Entry(Timetable        *timetable,
                         const Datetime&   loadTime,
                         bslma::Allocator *allocator);
 
    /// Create a cache entry object having the value of the specified
    /// `original` object.
    TimetableCache_Entry(const TimetableCache_Entry& original);
 
    /// Destroy this cache entry object.
    ~TimetableCache_Entry();
 
    // MANIPULATORS
 
    /// Assign to this cache entry object the value of the specified `rhs`
    /// object, and return a reference providing modifiable access to this
    /// object.
    TimetableCache_Entry& operator=(const TimetableCache_Entry& rhs);
 
    // ACCESSORS
 
    /// Return a shared pointer providing non-modifiable access to the
    /// timetable referred to by this cache entry object.
    bsl::shared_ptr<const Timetable> get() const;
 
    /// Return the time at which the timetable referred to by this cache
    /// entry object was loaded.
    Datetime loadTime() const;
};
 
                           // ====================
                           // class TimetableCache
                           // ====================
 
/// This class implements an efficient cache of *read-only*
/// `bdlt::Timetable` objects that are loaded into the cache, using a
/// timetable loader supplied at construction, as a side-effect of the
/// `getTimetable` manipulator.  Timetables in the cache can be invalidated,
/// and removed from the cache via the `invalidate` and `invalidateAll`
/// methods.  In addition, timetables in the cache can be made to expire
/// based on a timeout that may be optionally supplied at construction.  The
/// `bsl::shared_ptr<const bdlt::Timetable>` objects returned from the
/// `getTimetable` and `lookupTimetable` methods allow for the safe removal
/// of timetables from the cache that may still have outstanding references
/// to them.
///
/// This container is *exception* *neutral* with no guarantee of rollback:
/// if an exception is thrown during the invocation of a method on a
/// pre-existing instance, the container is left in a valid state, but its
/// value is undefined.  In no event is memory leaked.
///
/// This class is fully thread-safe (see @ref bsldoc_glossary ).
///
/// See @ref bdlt_timetablecache 
class TimetableCache {
 
    // DATA
    mutable bsl::map<bsl::string, TimetableCache_Entry>
                           d_cache;           // cache of (name, handle) pairs
 
    TimetableLoader       *d_loader_p;        // timetable loader (held, not
                                              // owned)
 
    DatetimeInterval       d_timeOut;         // timeout value; ignored unless
                                              // 'd_hasTimeOutFlag' is 'true'
 
    bool                   d_hasTimeOutFlag;  // 'true' if this cache has a
                                              // timeout value and 'false'
                                              // otherwise
 
    mutable bslmt::Mutex   d_lock;            // guard access to cache
 
    bslma::Allocator      *d_allocator_p;     // memory allocator (held, not
                                              // owned)
 
  private:
    // PRIVATE TYPES
    typedef bsl::map<bsl::string, TimetableCache_Entry>::iterator
                                                                 CacheIterator;
 
    typedef bsl::map<bsl::string, TimetableCache_Entry>::const_iterator
                                                            ConstCacheIterator;
 
  private:
    // NOT IMPLEMENTED
    TimetableCache(const TimetableCache&);
    TimetableCache& operator=(const TimetableCache&);
 
  public:
    // TRAITS
 
    BSLMF_NESTED_TRAIT_DECLARATION(TimetableCache, bslma::UsesBslmaAllocator);
 
    // CREATORS
 
    /// Create an empty timetable cache that uses the specified `loader` to
    /// load timetables on demand and has no timeout.  Optionally specify a
    /// `basicAllocator` used to supply memory.  If `basicAllocator` is 0,
    /// the currently installed default allocator is used.  Timetables
    /// loaded into this cache remain valid for retrieval until they have
    /// been explicitly invalidated (via either the `invalidate` or
    /// `invalidateAll` methods), or until this object is destroyed.  
    /// 
    /// \pre The behavior is undefined   unless `loader` remains valid throughout the
    /// lifetime of this cache.
    explicit
    TimetableCache(TimetableLoader  *loader,
                   bslma::Allocator *basicAllocator = 0);
 
    /// Create an empty timetable cache that uses the specified `loader` to
    /// load timetables on demand and has the specified `timeout` interval
    /// indicating the length of time that timetables remain valid for
    /// subsequent retrieval from the cache after they have been loaded.
    /// Optionally specify a `basicAllocator` used to supply memory.  If
    /// `basicAllocator` is 0, the currently installed default allocator is used.  
    /// 
    /// \pre The behavior is undefined   unless
    /// `bsls::TimeInterval() <= timeout <= bsls::TimeInterval(INT_MAX, 0)`,
    /// and `loader` remains valid throughout the lifetime of this cache. 
    /// 
    /// \note Note that   a `timeout` value of 0 indicates that a timetable will be
    /// loaded into the cache by *each* (successful) call to the
    /// `getTimetable` method.
    TimetableCache(TimetableLoader           *loader,
                   const bsls::TimeInterval&  timeout,
                   bslma::Allocator          *basicAllocator = 0);
 
    /// Destroy this object.
    ~TimetableCache();
 
    // MANIPULATORS
 
    /// Return a shared pointer providing non-modifiable access to the
    /// timetable having the specified `timetableName` in this timetable
    /// cache, loading the timetable into the cache using the loader that
    /// was supplied at construction if the timetable is not already present
    /// in the cache or if the timetable has expired (i.e., per a timeout
    /// optionally supplied at construction).  If the loader fails, whether
    /// in loading a timetable for the first time or in reloading a
    /// timetable that has expired, return an empty shared pointer.
    bsl::shared_ptr<const Timetable> getTimetable(const char *timetableName);
 
    /// Invalidate the timetable having the specified `timetableName` in
    /// this timetable cache, and remove it from the cache.  If a timetable
    /// having `timetableName` is not present in this cache, this method has
    /// no effect.  Return the number of timetables that were invalidated. 
    /// 
    /// \note Note that   a timetable that has been invalidated in the cache remains
    /// valid to all outstanding references to it, obtained via earlier
    /// calls to the `getTimetable` and `lookupTimetable` methods, until all
    /// of those references have been destroyed.
    int invalidate(const char *timetableName);
 
    /// Invalidate all timetables in this timetable cache, and remove them
    /// from the cache.  Return the number of timetables that were invalidated.  
    /// 
    /// \note Note that   a timetable that has been invalidated in the
    /// cache remains valid to all outstanding references to it, obtained
    /// via earlier calls to the `getTimetable` and `lookupTimetable`
    /// methods, until all of those references have been destroyed.
    int invalidateAll();
 
    // ACCESSORS
 
    /// Return a shared pointer providing non-modifiable access to the
    /// timetable having the specified `timetableName` in this timetable
    /// cache.  If the timetable having `timetableName` is not found in the
    /// cache, or if the timetable has expired (i.e., per a timeout
    /// optionally supplied at construction), return an empty shared
    /// pointer.
    bsl::shared_ptr<const Timetable>
    lookupTimetable(const char *timetableName) const;
 
    /// Return the datetime, in Coordinated Universal Time (UTC), at which
    /// the timetable having the specified `timetableName` was loaded into
    /// this timetable cache.  If the timetable having `timetableName` is
    /// not found in the cache, or if the timetable has expired (i.e., per a
    /// timeout optionally supplied at construction), return `Datetime()`.
    Datetime lookupLoadTime(const char *timetableName) const;
};
 
// ============================================================================
//                             INLINE DEFINITIONS
// ============================================================================
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2018 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */