Class program_cache

| Home | Libraries | People | FAQ | More

## Class program_cache

boost::compute::program_cache

## Synopsis

    // In header: <boost/compute/utility/program_cache.hpp>

    class program_cache : private noncopyable {
    public:
      // construct/copy/destruct
      program_cache(size_t);
      ~program_cache();

      // public member functions
      size_t size() const;
      size_t capacity() const;
      void clear();
      boost::optional< program > get(const std::string &);
      boost::optional< program > get(const std::string &, const std::string &);
      void insert(const std::string &, const program &);
      void insert(const std::string &, const std::string &, const program &);
      program get_or_build(const std::string &, const std::string &,
                           const std::string &, const context &);

      // public static functions
      static boost::shared_ptr< program_cache > get_global_cache(const context &);
    };

## Description

The program_cache class stores program objects in a LRU cache.

This class can be used to help mitigate the overhead of OpenCL's run-time kernel compilation model. Commonly used programs can be stored persistently in the cache and only compiled once on their first use.

Program objects are stored and retreived based on a user-defined cache key along with the options used to build the program (if any).

For example, to insert a program into the cache:

    cache.insert("foo", foo_program);

And to retreive the program later:

    boost::optional<program> p = cache.get("foo");
    if(p){
        // program found in cache
    }

See Also:

program

### `program_cache` public construct/copy/destruct

1.     program_cache(size_t capacity);

   Creates a new program cache with space for `capacity` number of program objects.

2.     ~program_cache();

   Destroys the program cache.

### `program_cache` public member functions

1.     size_t size() const;

   Returns the number of program objects currently stored in the cache.

2.     size_t capacity() const;

   Returns the total capacity of the cache.

3.     void clear();

   Clears the program cache.

4.     boost::optional< program > get(const std::string & key);

   Returns the program object with `key`. Returns a null optional if no program with `key` exists in the cache.

5.     boost::optional< program >
       get(const std::string & key, const std::string & options);

   Returns the program object with `key` and `options`. Returns a null optional if no program with `key` and `options` exists in the cache.

6.     void insert(const std::string & key, const program & program);

   Inserts `program` into the cache with `key`.

7.     void insert(const std::string & key, const std::string & options,
                   const program & program);

   Inserts `program` into the cache with `key` and `options`.

8.     program get_or_build(const std::string & key, const std::string & options,
                            const std::string & source, const context & context);

   Loads the program with `key` from the cache if it exists. Otherwise builds a new program with `source` and `options`, stores it in the cache, and returns it.

   This is a convenience function to simplify the common pattern of attempting to load a program from the cache and, if not present, building the program from source and storing it in the cache.

   Equivalent to:

       boost::optional<program> p = get(key, options);
       if(!p){
           p = program::create_with_source(source, context);
           p->build(options);
           insert(key, options, *p);
       }
       return *p;

### `program_cache` public static functions

1.     static boost::shared_ptr< program_cache >
       get_global_cache(const context & context);

   Returns the global program cache for `context`.

   This global cache is used internally by Boost.Compute to store compiled program objects used by its algorithms. All Boost.Compute programs are stored with a cache key beginning with `"__boost"`. User programs should avoid using the same prefix in order to prevent collisions.