Component bdlt_defaultcalendarcache [Package bdlt]

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

Namespaces
namespace	bdlt

---

Detailed Description

Outline

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

Purpose:

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

Classes:

bdlt::DefaultCalendarCache

namespace for managing a default calendar cache

See also:

Component bdlt_calendarcache, Component bdlt_calendarloader

Description:

This component provides a namespace, bdlt::DefaultCalendarCache, for utility functions that initialize, provide access to, and ultimately destroy, a default bdlt::CalendarCache object. The default cache is initialized by calling the (overloaded) initialize class method to which a concrete calendar loader and memory allocator must be supplied. The cache is destroyed by the destroy class method. Note that the calendar-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 calendar from the cache may incur the reloading of the calendar if the one in the cache has expired (i.e., the time interval defined by the timeout value has elapsed since the calendar was last loaded into the cache). Calendars 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 calendar loader and memory allocator supplied to initialize must extend beyond the following (matching) call to destroy. While the default calendar 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::DefaultCalendarCache 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::DefaultCalendarCache.

Example 1: Using bdlt::DefaultCalendarCache:

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

A hypothetical calendar loader is assumed, MyCalendarLoader, the details of which are not important other than that it supports calendars identified by "DE", "FR", and "US", which nominally identify the major holidays in Germany, France, and the United States, respectively. Furthermore, we cite two specific dates of interest: 2011/07/04, which was a holiday in the US (Independence Day), but not in France, and 2011/07/14, which was a holiday in France (Bastille Day), but not in the US.

First, we create a calendar loader, an instance of MyCalendarLoader, and use it, in turn, to initialize the default calendar 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 MyCalendarLoader loader;

  int rc = bdlt::DefaultCalendarCache::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 calendar cache using the instance class method:

  bdlt::CalendarCache *cachePtr = bdlt::DefaultCalendarCache::instance();
  assert(cachePtr);

Then, we retrieve the calendar identified by "US" from the default cache, and verify that 2011/07/04 is recognized as a holiday in the "US" calendar, whereas 2011/07/14 is not:

  bsl::shared_ptr<const bdlt::Calendar> us = cachePtr->getCalendar("US");
  assert( us->isHoliday(bdlt::Date(2011, 7,  4)));
  assert(!us->isHoliday(bdlt::Date(2011, 7, 14)));

Next, we fetch the calendar identified by "FR", this time verifying that 2011/07/14 is recognized as a holiday in the "FR" calendar, but 2011/07/04 is not:

  bsl::shared_ptr<const bdlt::Calendar> fr = cachePtr->getCalendar("FR");
  assert(!fr->isHoliday(bdlt::Date(2011, 7,  4)));
  assert( fr->isHoliday(bdlt::Date(2011, 7, 14)));

Finally, we destroy the default calendar cache:

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

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