1 //---------------------------------------------------------------------------//
2 // Copyright (c) 2013 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_ITERATOR_BUFFER_ITERATOR_HPP
12 #define BOOST_COMPUTE_ITERATOR_BUFFER_ITERATOR_HPP
17 #include <boost/config.hpp>
18 #include <boost/type_traits.hpp>
19 #include <boost/static_assert.hpp>
20 #include <boost/utility/enable_if.hpp>
21 #include <boost/iterator/iterator_facade.hpp>
23 #include <boost/compute/buffer.hpp>
24 #include <boost/compute/detail/buffer_value.hpp>
25 #include <boost/compute/detail/is_buffer_iterator.hpp>
26 #include <boost/compute/detail/meta_kernel.hpp>
27 #include <boost/compute/detail/read_write_single_value.hpp>
28 #include <boost/compute/type_traits/is_device_iterator.hpp>
33 // forward declaration for buffer_iterator<T>
34 template<class T> class buffer_iterator;
38 // helper class which defines the iterator_facade super-class
39 // type for buffer_iterator<T>
41 class buffer_iterator_base
44 typedef ::boost::iterator_facade<
45 ::boost::compute::buffer_iterator<T>,
47 ::std::random_access_iterator_tag,
48 ::boost::compute::detail::buffer_value<T>
52 template<class T, class IndexExpr>
53 struct buffer_iterator_index_expr
55 typedef T result_type;
57 buffer_iterator_index_expr(const buffer &buffer,
59 const memory_object::address_space address_space,
60 const IndexExpr &expr)
63 m_address_space(address_space),
70 BOOST_STATIC_ASSERT_MSG(boost::is_integral<IndexExpr>::value,
71 "Index expression must be integral");
73 return buffer_value<T>(m_buffer, size_t(m_expr) * sizeof(T));
76 const buffer &m_buffer;
78 memory_object::address_space m_address_space;
82 template<class T, class IndexExpr>
83 inline meta_kernel& operator<<(meta_kernel &kernel,
84 const buffer_iterator_index_expr<T, IndexExpr> &expr)
86 if(expr.m_index == 0){
88 kernel.get_buffer_identifier<T>(expr.m_buffer, expr.m_address_space) <<
89 '[' << expr.m_expr << ']';
93 kernel.get_buffer_identifier<T>(expr.m_buffer, expr.m_address_space) <<
94 '[' << uint_(expr.m_index) << "+(" << expr.m_expr << ")]";
98 } // end detail namespace
100 /// \class buffer_iterator
101 /// \brief An iterator for values in a buffer.
103 /// The buffer_iterator class iterates over values in a memory buffer on a
104 /// compute device. It is the most commonly used iterator in Boost.Compute
105 /// and is used by the \ref vector "vector<T>" and \ref array "array<T, N>"
106 /// container classes.
108 /// Buffer iterators store a reference to a memory buffer along with an index
109 /// into that memory buffer.
111 /// The buffer_iterator class allows for arbitrary OpenCL memory objects
112 /// (including those created outside of Boost.Compute) to be used with the
113 /// Boost.Compute algorithms (such as transform() and sort()). For example,
114 /// to reverse the contents of an OpenCL memory buffer containing a set of
117 /// \snippet test/test_buffer_iterator.cpp reverse_external_buffer
119 /// \see buffer, make_buffer_iterator()
121 class buffer_iterator : public detail::buffer_iterator_base<T>::type
124 typedef typename detail::buffer_iterator_base<T>::type super_type;
125 typedef typename super_type::reference reference;
126 typedef typename super_type::difference_type difference_type;
133 buffer_iterator(const buffer &buffer, size_t index)
134 : m_buffer(buffer.get(), false),
139 buffer_iterator(const buffer_iterator<T> &other)
140 : m_buffer(other.m_buffer.get(), false),
141 m_index(other.m_index)
145 buffer_iterator<T>& operator=(const buffer_iterator<T> &other)
148 m_buffer.get() = other.m_buffer.get();
149 m_index = other.m_index;
157 // set buffer to null so that its reference count will
158 // not be decremented when its destructor is called
162 const buffer& get_buffer() const
167 size_t get_index() const
172 T read(command_queue &queue) const
174 BOOST_ASSERT(m_buffer.get());
175 BOOST_ASSERT(m_index < m_buffer.size() / sizeof(T));
177 return detail::read_single_value<T>(m_buffer, m_index, queue);
180 void write(const T &value, command_queue &queue)
182 BOOST_ASSERT(m_buffer.get());
183 BOOST_ASSERT(m_index < m_buffer.size() / sizeof(T));
185 detail::write_single_value<T>(value, m_buffer, m_index, queue);
190 detail::buffer_iterator_index_expr<T, Expr>
191 operator[](const Expr &expr) const
193 BOOST_ASSERT(m_buffer.get());
195 return detail::buffer_iterator_index_expr<T, Expr>(
196 m_buffer, m_index, memory_object::global_memory, expr
201 friend class ::boost::iterator_core_access;
204 reference dereference() const
206 return detail::buffer_value<T>(m_buffer, m_index * sizeof(T));
210 bool equal(const buffer_iterator<T> &other) const
212 return m_buffer.get() == other.m_buffer.get() &&
213 m_index == other.m_index;
229 void advance(difference_type n)
231 m_index = static_cast<size_t>(static_cast<difference_type>(m_index) + n);
235 difference_type distance_to(const buffer_iterator<T> &other) const
237 return static_cast<difference_type>(other.m_index - m_index);
241 const buffer m_buffer;
245 /// Creates a new \ref buffer_iterator for \p buffer at \p index.
247 /// \param buffer the \ref buffer object
248 /// \param index the index in the buffer
250 /// \return a \c buffer_iterator for \p buffer at \p index
252 inline buffer_iterator<T>
253 make_buffer_iterator(const buffer &buffer, size_t index = 0)
255 return buffer_iterator<T>(buffer, index);
258 /// \internal_ (is_device_iterator specialization for buffer_iterator)
260 struct is_device_iterator<buffer_iterator<T> > : boost::true_type {};
264 // is_buffer_iterator specialization for buffer_iterator
265 template<class Iterator>
266 struct is_buffer_iterator<
268 typename boost::enable_if<
270 buffer_iterator<typename Iterator::value_type>,
271 typename boost::remove_const<Iterator>::type
274 > : public boost::true_type {};
276 } // end detail namespace
277 } // end compute namespace
278 } // end boost namespace
280 #endif // BOOST_COMPUTE_ITERATOR_BUFFER_ITERATOR_HPP