Component bdlt_defaulttimetablecache [Package bdlt]

Provide a process-wide default bdlt::TimetableCache object. More...

Namespaces
namespace	bdlt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Using bdlt::DefaultTimetableCache

Purpose:

Provide a process-wide default bdlt::TimetableCache object.

Classes:

bdlt::DefaultTimetableCache

namespace managing a default timetable cache

See also:

Component bdlt_timetablecache, Component bdlt_timetableloader

Description:

This component provides a namespace, bdlt::DefaultTimetableCache, for utility functions that initialize, provide access to, and ultimately destroy, a default bdlt::TimetableCache object. The default cache is initialized by calling the (overloaded) initialize class method to which a concrete timetable loader and memory allocator must be supplied. The cache is destroyed by the destroy class method. Note that the timetable-naming convention in effect for the default cache is determined by the loader supplied to initialize.

A timeout may be established for the default cache by supplying an optional bsls::TimeInterval value to initialize. When a timeout is in effect for the default cache, a request for a timetable from the cache 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 into the cache). Timetables will not expire in this fashion if the default cache is not provided with a timeout at initialization.

Although the cache may be initialized and destroyed multiple times during the lifetime of a process, the expected usage is that the cache would be initialized once, typically in main before other threads have been created, and destroyed just prior to program termination. Regardless, the lifetimes of the timetable loader and memory allocator supplied to initialize must extend beyond the following (matching) call to destroy. While the default timetable cache is in the initialized state, the instance method returns an address providing modifiable access to the cache. Otherwise, instance returns 0.

WARNING: Clients should be aware that the address returned by instance becomes invalid by a subsequent call to destroy.

Thread Safety:

The bdlt::DefaultTimetableCache class is fully thread-safe (see bsldoc_glossary) provided that the allocator supplied to initialize and the default allocator in effect during the lifetime of the default cache are both fully thread-safe.

Usage:

The following example illustrates how to use bdlt::DefaultTimetableCache.

Example 1: Using bdlt::DefaultTimetableCache:

bdlt::DefaultTimetableCache has a particularly simple interface. This example shows how to use each of its three methods.

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 initialize the default timetable cache. A memory allocator must also be explicitly supplied to the initialize method. The global allocator is suitable in this case (see bslma_default):

  static MyTimetableLoader loader;

  int rc = bdlt::DefaultTimetableCache::initialize(
                                          &loader,
                                          bslma::Default::globalAllocator());
  assert(!rc);

Note that declaring loader to be static ensures that it remains valid until the cache is destroyed. Also note that initialization of the cache would typically be done in main before other threads have been created.

Next, we obtain the address of the default timetable cache using the instance class method:

  bdlt::TimetableCache *cachePtr = bdlt::DefaultTimetableCache::instance();
  assert(cachePtr);

Then, we retrieve the timetable identified by "TWO" from the default cache and verify that 2 is the value of the initial transition code:

  bsl::shared_ptr<const bdlt::Timetable> two = cachePtr->getTimetable("TWO");
  assert(2 == two->initialTransitionCode());

Next, we fetch the timetable identified by "ONE", this time verifying that 1 is the value of the initial transition code for the "ONE" timetable:

  bsl::shared_ptr<const bdlt::Timetable> one = cachePtr->getTimetable("ONE");
  assert(1 == one->initialTransitionCode());

Finally, we destroy the default timetable cache:

  bdlt::DefaultTimetableCache::destroy();
  assert(!bdlt::DefaultTimetableCache::instance());

Note that destruction of the default cache would typically be done in main just prior to program termination.