1 //---------------------------------------------------------------------------//
2 // Copyright (c) 2013 Kyle Lutz <kyle.r.lutz@gmail.com>
3 //
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
7 //
8 // See http://boostorg.github.com/compute for more information.
9 //---------------------------------------------------------------------------//
10
11 #ifndef BOOST_COMPUTE_ITERATOR_BUFFER_ITERATOR_HPP
12 #define BOOST_COMPUTE_ITERATOR_BUFFER_ITERATOR_HPP
13
14 #include <cstddef>
15 #include <iterator>
16
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>
22
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>
29
30 namespace boost {
31 namespace compute {
32
33 // forward declaration for buffer_iterator<T>
34 template<class T> class buffer_iterator;
35
36 namespace detail {
37
38 // helper class which defines the iterator_facade super-class
39 // type for buffer_iterator<T>
40 template<class T>
41 class buffer_iterator_base
42 {
43 public:
44 typedef ::boost::iterator_facade<
45 ::boost::compute::buffer_iterator<T>,
46 T,
47 ::std::random_access_iterator_tag,
48 ::boost::compute::detail::buffer_value<T>
49 > type;
50 };
51
52 template<class T, class IndexExpr>
53 struct buffer_iterator_index_expr
54 {
55 typedef T result_type;
56
buffer_iterator_index_exprboost::compute::detail::buffer_iterator_index_expr57 buffer_iterator_index_expr(const buffer &buffer,
58 size_t index,
59 const memory_object::address_space address_space,
60 const IndexExpr &expr)
61 : m_buffer(buffer.get(), false),
62 m_index(index),
63 m_address_space(address_space),
64 m_expr(expr)
65 {
66 }
67
buffer_iterator_index_exprboost::compute::detail::buffer_iterator_index_expr68 buffer_iterator_index_expr(const buffer_iterator_index_expr& other)
69 : m_buffer(other.m_buffer.get(), false),
70 m_index(other.m_index),
71 m_address_space(other.m_address_space),
72 m_expr(other.m_expr)
73 {
74 }
75
~buffer_iterator_index_exprboost::compute::detail::buffer_iterator_index_expr76 ~buffer_iterator_index_expr()
77 {
78 // set buffer to null so that its reference count will
79 // not be decremented when its destructor is called
80 m_buffer.get() = 0;
81 }
82
operator Tboost::compute::detail::buffer_iterator_index_expr83 operator T() const
84 {
85 BOOST_STATIC_ASSERT_MSG(boost::is_integral<IndexExpr>::value,
86 "Index expression must be integral");
87
88 return buffer_value<T>(m_buffer, size_t(m_expr) * sizeof(T));
89 }
90
91 const buffer m_buffer;
92 const size_t m_index;
93 const memory_object::address_space m_address_space;
94 const IndexExpr m_expr;
95 };
96
97 template<class T, class IndexExpr>
operator <<(meta_kernel & kernel,const buffer_iterator_index_expr<T,IndexExpr> & expr)98 inline meta_kernel& operator<<(meta_kernel &kernel,
99 const buffer_iterator_index_expr<T, IndexExpr> &expr)
100 {
101 if(expr.m_index == 0){
102 return kernel <<
103 kernel.get_buffer_identifier<T>(expr.m_buffer, expr.m_address_space) <<
104 '[' << expr.m_expr << ']';
105 }
106 else {
107 return kernel <<
108 kernel.get_buffer_identifier<T>(expr.m_buffer, expr.m_address_space) <<
109 '[' << uint_(expr.m_index) << "+(" << expr.m_expr << ")]";
110 }
111 }
112
113 } // end detail namespace
114
115 /// \class buffer_iterator
116 /// \brief An iterator for values in a buffer.
117 ///
118 /// The buffer_iterator class iterates over values in a memory buffer on a
119 /// compute device. It is the most commonly used iterator in Boost.Compute
120 /// and is used by the \ref vector "vector<T>" and \ref array "array<T, N>"
121 /// container classes.
122 ///
123 /// Buffer iterators store a reference to a memory buffer along with an index
124 /// into that memory buffer.
125 ///
126 /// The buffer_iterator class allows for arbitrary OpenCL memory objects
127 /// (including those created outside of Boost.Compute) to be used with the
128 /// Boost.Compute algorithms (such as transform() and sort()). For example,
129 /// to reverse the contents of an OpenCL memory buffer containing a set of
130 /// integers:
131 ///
132 /// \snippet test/test_buffer_iterator.cpp reverse_external_buffer
133 ///
134 /// \see buffer, make_buffer_iterator()
135 template<class T>
136 class buffer_iterator : public detail::buffer_iterator_base<T>::type
137 {
138 public:
139 typedef typename detail::buffer_iterator_base<T>::type super_type;
140 typedef typename super_type::reference reference;
141 typedef typename super_type::difference_type difference_type;
142
buffer_iterator()143 buffer_iterator()
144 : m_index(0)
145 {
146 }
147
buffer_iterator(const buffer & buffer,size_t index)148 buffer_iterator(const buffer &buffer, size_t index)
149 : m_buffer(buffer.get(), false),
150 m_index(index)
151 {
152 }
153
buffer_iterator(const buffer_iterator<T> & other)154 buffer_iterator(const buffer_iterator<T> &other)
155 : m_buffer(other.m_buffer.get(), false),
156 m_index(other.m_index)
157 {
158 }
159
operator =(const buffer_iterator<T> & other)160 buffer_iterator<T>& operator=(const buffer_iterator<T> &other)
161 {
162 if(this != &other){
163 m_buffer.get() = other.m_buffer.get();
164 m_index = other.m_index;
165 }
166
167 return *this;
168 }
169
~buffer_iterator()170 ~buffer_iterator()
171 {
172 // set buffer to null so that its reference count will
173 // not be decremented when its destructor is called
174 m_buffer.get() = 0;
175 }
176
get_buffer() const177 const buffer& get_buffer() const
178 {
179 return m_buffer;
180 }
181
get_index() const182 size_t get_index() const
183 {
184 return m_index;
185 }
186
read(command_queue & queue) const187 T read(command_queue &queue) const
188 {
189 BOOST_ASSERT(m_buffer.get());
190 BOOST_ASSERT(m_index < m_buffer.size() / sizeof(T));
191
192 return detail::read_single_value<T>(m_buffer, m_index, queue);
193 }
194
write(const T & value,command_queue & queue)195 void write(const T &value, command_queue &queue)
196 {
197 BOOST_ASSERT(m_buffer.get());
198 BOOST_ASSERT(m_index < m_buffer.size() / sizeof(T));
199
200 detail::write_single_value<T>(value, m_buffer, m_index, queue);
201 }
202
203 /// \internal_
204 template<class Expr>
205 detail::buffer_iterator_index_expr<T, Expr>
operator [](const Expr & expr) const206 operator[](const Expr &expr) const
207 {
208 BOOST_ASSERT(m_buffer.get());
209
210 return detail::buffer_iterator_index_expr<T, Expr>(
211 m_buffer, m_index, memory_object::global_memory, expr
212 );
213 }
214
215 private:
216 friend class ::boost::iterator_core_access;
217
218 /// \internal_
dereference() const219 reference dereference() const
220 {
221 return detail::buffer_value<T>(m_buffer, m_index * sizeof(T));
222 }
223
224 /// \internal_
equal(const buffer_iterator<T> & other) const225 bool equal(const buffer_iterator<T> &other) const
226 {
227 return m_buffer.get() == other.m_buffer.get() &&
228 m_index == other.m_index;
229 }
230
231 /// \internal_
increment()232 void increment()
233 {
234 m_index++;
235 }
236
237 /// \internal_
decrement()238 void decrement()
239 {
240 m_index--;
241 }
242
243 /// \internal_
advance(difference_type n)244 void advance(difference_type n)
245 {
246 m_index = static_cast<size_t>(static_cast<difference_type>(m_index) + n);
247 }
248
249 /// \internal_
distance_to(const buffer_iterator<T> & other) const250 difference_type distance_to(const buffer_iterator<T> &other) const
251 {
252 return static_cast<difference_type>(other.m_index - m_index);
253 }
254
255 private:
256 const buffer m_buffer;
257 size_t m_index;
258 };
259
260 /// Creates a new \ref buffer_iterator for \p buffer at \p index.
261 ///
262 /// \param buffer the \ref buffer object
263 /// \param index the index in the buffer
264 ///
265 /// \return a \c buffer_iterator for \p buffer at \p index
266 template<class T>
267 inline buffer_iterator<T>
make_buffer_iterator(const buffer & buffer,size_t index=0)268 make_buffer_iterator(const buffer &buffer, size_t index = 0)
269 {
270 return buffer_iterator<T>(buffer, index);
271 }
272
273 /// \internal_ (is_device_iterator specialization for buffer_iterator)
274 template<class T>
275 struct is_device_iterator<buffer_iterator<T> > : boost::true_type {};
276
277 namespace detail {
278
279 // is_buffer_iterator specialization for buffer_iterator
280 template<class Iterator>
281 struct is_buffer_iterator<
282 Iterator,
283 typename boost::enable_if<
284 boost::is_same<
285 buffer_iterator<typename Iterator::value_type>,
286 typename boost::remove_const<Iterator>::type
287 >
288 >::type
289 > : public boost::true_type {};
290
291 } // end detail namespace
292 } // end compute namespace
293 } // end boost namespace
294
295 #endif // BOOST_COMPUTE_ITERATOR_BUFFER_ITERATOR_HPP
296