1 //---------------------------------------------------------------------------//
2 // Copyright (c) 2013-2014 Kyle Lutz <kyle.r.lutz@gmail.com>
4 // Distributed under the Boost Software License, Version 1.0
5 // See accompanying file LICENSE_1_0.txt or copy at
6 // http://www.boost.org/LICENSE_1_0.txt
8 // See http://boostorg.github.com/compute for more information.
9 //---------------------------------------------------------------------------//
11 #ifndef BOOST_COMPUTE_UTILITY_PROGRAM_CACHE_HPP
12 #define BOOST_COMPUTE_UTILITY_PROGRAM_CACHE_HPP
17 #include <boost/shared_ptr.hpp>
18 #include <boost/make_shared.hpp>
19 #include <boost/noncopyable.hpp>
21 #include <boost/compute/context.hpp>
22 #include <boost/compute/program.hpp>
23 #include <boost/compute/detail/lru_cache.hpp>
24 #include <boost/compute/detail/global_static.hpp>
29 /// The program_cache class stores \ref program objects in a LRU cache.
31 /// This class can be used to help mitigate the overhead of OpenCL's run-time
32 /// kernel compilation model. Commonly used programs can be stored persistently
33 /// in the cache and only compiled once on their first use.
35 /// Program objects are stored and retreived based on a user-defined cache key
36 /// along with the options used to build the program (if any).
38 /// For example, to insert a program into the cache:
40 /// cache.insert("foo", foo_program);
43 /// And to retreive the program later:
45 /// boost::optional<program> p = cache.get("foo");
47 /// // program found in cache
52 class program_cache : boost::noncopyable
55 /// Creates a new program cache with space for \p capacity number of
57 program_cache(size_t capacity)
62 /// Destroys the program cache.
67 /// Returns the number of program objects currently stored in the cache.
70 return m_cache.size();
73 /// Returns the total capacity of the cache.
74 size_t capacity() const
76 return m_cache.capacity();
79 /// Clears the program cache.
85 /// Returns the program object with \p key. Returns a null optional if no
86 /// program with \p key exists in the cache.
87 boost::optional<program> get(const std::string &key)
89 return m_cache.get(std::make_pair(key, std::string()));
92 /// Returns the program object with \p key and \p options. Returns a null
93 /// optional if no program with \p key and \p options exists in the cache.
94 boost::optional<program> get(const std::string &key, const std::string &options)
96 return m_cache.get(std::make_pair(key, options));
99 /// Inserts \p program into the cache with \p key.
100 void insert(const std::string &key, const program &program)
102 insert(key, std::string(), program);
105 /// Inserts \p program into the cache with \p key and \p options.
106 void insert(const std::string &key, const std::string &options, const program &program)
108 m_cache.insert(std::make_pair(key, options), program);
111 /// Loads the program with \p key from the cache if it exists. Otherwise
112 /// builds a new program with \p source and \p options, stores it in the
113 /// cache, and returns it.
115 /// This is a convenience function to simplify the common pattern of
116 /// attempting to load a program from the cache and, if not present,
117 /// building the program from source and storing it in the cache.
121 /// boost::optional<program> p = get(key, options);
123 /// p = program::create_with_source(source, context);
124 /// p->build(options);
125 /// insert(key, options, *p);
129 program get_or_build(const std::string &key,
130 const std::string &options,
131 const std::string &source,
132 const context &context)
134 boost::optional<program> p = get(key, options);
136 p = program::build_with_source(source, context, options);
138 insert(key, options, *p);
143 /// Returns the global program cache for \p context.
145 /// This global cache is used internally by Boost.Compute to store compiled
146 /// program objects used by its algorithms. All Boost.Compute programs are
147 /// stored with a cache key beginning with \c "__boost". User programs
148 /// should avoid using the same prefix in order to prevent collisions.
149 static boost::shared_ptr<program_cache> get_global_cache(const context &context)
151 typedef detail::lru_cache<cl_context, boost::shared_ptr<program_cache> > cache_map;
153 BOOST_COMPUTE_DETAIL_GLOBAL_STATIC(cache_map, caches, (8));
155 boost::optional<boost::shared_ptr<program_cache> > cache = caches.get(context.get());
157 cache = boost::make_shared<program_cache>(64);
159 caches.insert(context.get(), *cache);
166 detail::lru_cache<std::pair<std::string, std::string>, program> m_cache;
169 } // end compute namespace
170 } // end boost namespace
172 #endif // BOOST_COMPUTE_UTILITY_PROGRAM_CACHE_HPP