libdap::HTTPCacheTable Class Reference

`#include <HTTPCacheTable.h>`

## Classes

struct | CacheEntry

## Public Types

typedef vector< CacheEntry * > | CacheEntries
typedef CacheEntries::iterator | CacheEntriesIter
typedef CacheEntries ** | CacheTable

## Public Member Functions

void | delete_by_hits (int hits)
void | delete_by_size (unsigned int size)
void | delete_expired_entries (time_t time=0)
unsigned int | get_block_size () const
string | get_cache_root ()
unsigned long | get_current_size () const
int | get_new_entries () const
| HTTPCacheTable (const string &cache_root, int block_size)
void | increment_new_entries ()
void | set_block_size (unsigned int sz)
void | set_cache_root (const string &cr)
void | set_current_size (unsigned long sz)
Cache Index
These methods manage the cache's index file. Each cache holds an index file named ``.index which stores the cache's state information.
bool | cache_index_delete ()
bool | cache_index_read ()
CacheEntry * | cache_index_parse_line (const char *line)
void | cache_index_write ()
string | create_hash_directory (int hash)
void | create_location (CacheEntry *entry)

## Friends

class | HTTPCacheTest

## Methods to manipulate instances of CacheEntry.

void | delete_all_entries ()
void | add_entry_to_cache_table (CacheEntry *entry)
void | remove_cache_entry (HTTPCacheTable::CacheEntry *entry)
void | remove_entry_from_cache_table (const string &url)
CacheEntry * | get_locked_entry_from_cache_table (const string &url)
CacheEntry * | get_write_locked_entry_from_cache_table (const string &url)
void | calculate_time (HTTPCacheTable::CacheEntry *entry, int default_expiration, time_t request_time)
void | parse_headers (HTTPCacheTable::CacheEntry *entry, unsigned long max_entry_size, const vector< string > &headers)
void | bind_entry_to_data (CacheEntry *entry, FILE *body)
void | uncouple_entry_from_data (FILE *body)
bool | is_locked_read_responses ()

## Detailed Description

The table of entries in the client-side cache. This class maintains a table of CacheEntries, where one instance of CacheEntry is made for each item in the cache. When an item is accessed it is either locked for reading or writing. When locked for reading the entry is recorded on a list of read-locked entries. The caller must explicitly free the entry for it to be removed from this list (which is the only way it can be opened for writing). An entry can be accessed by multiple readers but only one writer.

Note
  The CacheEntry class used to contain a lock that was used to ensure that the entry was locked during any changes to any of its fields. That has been removed - its now the responsibility of the caller. This change was made because it's likely the caller will need to lock all of the methods that operate on a CacheEntry anyway, so the CacheEntry-specific lock was redundant.

Definition at line 103 of file HTTPCacheTable.h.

## Member Typedef Documentation

## CacheEntries

typedef vector<CacheEntry *> libdap::HTTPCacheTable::CacheEntries

Definition at line 228 of file HTTPCacheTable.h.

## CacheEntriesIter

typedef CacheEntries::iterator libdap::HTTPCacheTable::CacheEntriesIter

Definition at line 229 of file HTTPCacheTable.h.

## CacheTable

typedef CacheEntries** libdap::HTTPCacheTable::CacheTable

Definition at line 231 of file HTTPCacheTable.h.

## Constructor & Destructor Documentation

## HTTPCacheTable()

libdap::HTTPCacheTable::HTTPCacheTable | ( | const string & | cache_root,
|  | int | block_size )

Definition at line 107 of file HTTPCacheTable.cc.

## ~HTTPCacheTable()

libdap::HTTPCacheTable::~HTTPCacheTable | ( |  | ) |

Definition at line 128 of file HTTPCacheTable.cc.

## Member Function Documentation

## add_entry_to_cache_table()

void libdap::HTTPCacheTable::add_entry_to_cache_table | ( | CacheEntry * | entry | ) |

Add a CacheEntry to the cache table. As each entry is read, load it into the in-memory cache table and update the HTTPCache's current_size. The later is used by the garbage collection method.

Parameters

  entry | The CacheEntry instance to add.

Definition at line 488 of file HTTPCacheTable.cc.

## bind_entry_to_data()

void libdap::HTTPCacheTable::bind_entry_to_data | ( | HTTPCacheTable::CacheEntry * | entry,
|  | FILE * | body )

Definition at line 761 of file HTTPCacheTable.cc.

## cache_index_delete()

bool libdap::HTTPCacheTable::cache_index_delete | ( |  | ) |

Remove the cache index file.

A private method.

Returns
  True if the file was deleted, otherwise false.

Definition at line 260 of file HTTPCacheTable.cc.

## cache_index_parse_line()

HTTPCacheTable::CacheEntry * libdap::HTTPCacheTable::cache_index_parse_line | ( | const char * | line | ) |

Parse one line of the index file.

A private method.

Parameters

  line | A single line from the ``.index file.

Returns
  A CacheEntry initialized with the information from `line`.

Definition at line 305 of file HTTPCacheTable.cc.

## cache_index_read()

bool libdap::HTTPCacheTable::cache_index_read | ( |  | ) |

Read the saved set of cached entries from disk. Consistency between the in-memory cache and the index is maintained by only reading the index file when the HTTPCache object is created!

A private method.

Returns
  True when a cache index was found and read, false otherwise.

Definition at line 274 of file HTTPCacheTable.cc.

## cache_index_write()

void libdap::HTTPCacheTable::cache_index_write | ( |  | ) |

Walk through the list of cached objects and write the cache index file to disk. If the file does not exist, it is created. If the file does exist, it is overwritten. As a side effect, zero the new_entries counter.

A private method.

Exceptions

  Error | Thrown if the index file cannot be opened for writing.

Note
  The HTTPCache destructor calls this method and silently ignores this exception.

Definition at line 360 of file HTTPCacheTable.cc.

## calculate_time()

void libdap::HTTPCacheTable::calculate_time | ( | HTTPCacheTable::CacheEntry * | entry,
|  | int | default_expiration,
|  | time_t | request_time )

Calculate the corrected_initial_age of the object. We use the time when this function is called as the response_time as this is when we have received the complete response. This may cause a delay if the response header is very big but should not cause any incorrect behavior.

A private method.

Parameters

  entry | The CacheEntry object.
  default_expiration | The default value of the cached object's expiration time.
  request_time | When was the request made? I think this value must be passed into the method that calls this method...

Definition at line 667 of file HTTPCacheTable.cc.

## create_hash_directory()

string libdap::HTTPCacheTable::create_hash_directory | ( | int | hash | ) |

Create the directory path for cache file. The cache uses a set of directories within d_cache_root to store individual responses. The name of the directory that holds a given response is the value returned by the get_hash() function (i.e., it's a number). If the directory exists, this method does nothing.

A private method.

Parameters

  hash | The hash value (i.e., directory name). An integer between 0 and CACHE_TABLE_SIZE (See HTTPCache.h).

Returns
  The pathname to the directory (even if it already existed).

Exceptions

  Error | Thrown if the directory cannot be created.

Definition at line 401 of file HTTPCacheTable.cc.

## create_location()

void libdap::HTTPCacheTable::create_location | ( | HTTPCacheTable::CacheEntry * | entry | ) |

Create the directory for this url (using the hash value from get_hash()) and a file within that directory to hold the response's information. The cache name and cache_body_fd fields of `entry` are updated.

mkstemp opens the file it creates, which is a good thing but it makes tracking resources hard for the HTTPCache object (because an exception might cause a file descriptor resource leak). So I close that file descriptor here.

A private method.

Parameters

  entry | The cache entry object to operate on.

Exceptions

  Error | If the file for the response's body cannot be created.

Definition at line 436 of file HTTPCacheTable.cc.

## delete_all_entries()

void libdap::HTTPCacheTable::delete_all_entries | ( |  | ) |

Definition at line 640 of file HTTPCacheTable.cc.

## delete_by_hits()

void libdap::HTTPCacheTable::delete_by_hits | ( | int | hits | ) |

Definition at line 206 of file HTTPCacheTable.cc.

## delete_by_size()

void libdap::HTTPCacheTable::delete_by_size | ( | unsigned int | size | ) |

Definition at line 237 of file HTTPCacheTable.cc.

## delete_expired_entries()

void libdap::HTTPCacheTable::delete_expired_entries | ( | time_t | time = 0 | ) |

Definition at line 172 of file HTTPCacheTable.cc.

## get_block_size()

unsigned int libdap::HTTPCacheTable::get_block_size | ( |  | ) | const

inline

Definition at line 264 of file HTTPCacheTable.h.

## get_cache_root()

string libdap::HTTPCacheTable::get_cache_root | ( |  | ) |

inline

Definition at line 270 of file HTTPCacheTable.h.

## get_current_size()

unsigned long libdap::HTTPCacheTable::get_current_size | ( |  | ) | const

inline

Definition at line 261 of file HTTPCacheTable.h.

## get_locked_entry_from_cache_table()

HTTPCacheTable::CacheEntry * libdap::HTTPCacheTable::get_locked_entry_from_cache_table | ( | const string & | url | ) |

Get a pointer to a CacheEntry from the cache table.

Parameters

  url | Look for this URL.

Definition at line 511 of file HTTPCacheTable.cc.

## get_new_entries()

int libdap::HTTPCacheTable::get_new_entries | ( |  | ) | const

inline

Definition at line 267 of file HTTPCacheTable.h.

## get_write_locked_entry_from_cache_table()

HTTPCacheTable::CacheEntry * libdap::HTTPCacheTable::get_write_locked_entry_from_cache_table | ( | const string & | url | ) |

Get a pointer to a CacheEntry from the cache table. Providing a way to pass the hash code into this method makes it easier to test for correct behavior when two entries collide. 10/07/02 jhrg

Parameters

  url | Look for this URL.

Returns
  The matching CacheEntry instance or NULL if none was found.

Definition at line 548 of file HTTPCacheTable.cc.

## increment_new_entries()

void libdap::HTTPCacheTable::increment_new_entries | ( |  | ) |

inline

Definition at line 268 of file HTTPCacheTable.h.

## is_locked_read_responses()

bool libdap::HTTPCacheTable::is_locked_read_responses | ( |  | ) |

Definition at line 779 of file HTTPCacheTable.cc.

## parse_headers()

void libdap::HTTPCacheTable::parse_headers | ( | HTTPCacheTable::CacheEntry * | entry,
|  | unsigned long | max_entry_size,
|  | const vector< string > & | headers )

Parse various headers from the vector (which can be retrieved from libcurl once a response is received) and load the CacheEntry object with values. This method should only be called with headers from a response (it should not be used to parse request headers).

A private method.

Parameters

  entry | Store values from the headers here.
  max_entry_size | DO not cache entries larger than this.
  headers | A vector of header lines.

Definition at line 706 of file HTTPCacheTable.cc.

## remove_cache_entry()

void libdap::HTTPCacheTable::remove_cache_entry | ( | HTTPCacheTable::CacheEntry * | entry | ) |

Remove a CacheEntry. This means delete the entry's files on disk and free the CacheEntry object. The caller should null the entry's pointer in the cache_table. The total size of the cache is decremented once the entry is deleted.

Parameters

  entry | The CacheEntry to delete.

Exceptions

  InternalErr | Thrown if `entry` is in use.

Definition at line 572 of file HTTPCacheTable.cc.

## remove_entry_from_cache_table()

void libdap::HTTPCacheTable::remove_entry_from_cache_table | ( | const string & | url | ) |

Find the CacheEntry for the given url and remove both its information in the persistent store and the entry in d_cache_table. If `url` is not in the cache, this method does nothing.

Parameters

  url | Remove this URL's entry.

Exceptions

  InternalErr | Thrown if the CacheEntry for `url` is locked.

Definition at line 615 of file HTTPCacheTable.cc.

## set_block_size()

void libdap::HTTPCacheTable::set_block_size | ( | unsigned int | sz | ) |

inline

Definition at line 265 of file HTTPCacheTable.h.

## set_cache_root()

void libdap::HTTPCacheTable::set_cache_root | ( | const string & | cr | ) |

inline

Definition at line 271 of file HTTPCacheTable.h.

## set_current_size()

void libdap::HTTPCacheTable::set_current_size | ( | unsigned long | sz | ) |

inline

Definition at line 262 of file HTTPCacheTable.h.

## uncouple_entry_from_data()

void libdap::HTTPCacheTable::uncouple_entry_from_data | ( | FILE * | body | ) |

Definition at line 766 of file HTTPCacheTable.cc.

## Friends And Related Symbol Documentation

## HTTPCacheTest

friend class HTTPCacheTest

friend

Definition at line 233 of file HTTPCacheTable.h.

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

- HTTPCacheTable.h
- HTTPCacheTable.cc