2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 * @file binary_queue.h
18 * @author Przemyslaw Dobrowolski (p.dobrowolsk@samsung.com)
20 * @brief This file is the header file of binary queue
22 #ifndef DPL_BINARY_QUEUE_H
23 #define DPL_BINARY_QUEUE_H
25 #include <dpl/abstract_input_output.h>
26 #include <dpl/exception.h>
27 #include <dpl/noncopyable.h>
33 * Binary stream implemented as constant size bucket list
35 * @todo Add optimized implementation for FlattenConsume
38 public AbstractInputOutput
44 DECLARE_EXCEPTION_TYPE(DPL::Exception, Base)
45 DECLARE_EXCEPTION_TYPE(Base, OutOfData)
48 typedef void (*BufferDeleter)(const void *buffer, size_t bufferSize,
50 static void BufferDeleterFree(const void *buffer,
60 virtual ~BucketVisitor();
66 * @param[in] buffer Constant pointer to bucket data buffer
67 * @param[in] bufferSize Number of bytes in bucket
69 virtual void OnVisitBucket(const void *buffer, size_t bufferSize) = 0;
81 BufferDeleter deleter;
84 Bucket(const void *buffer,
86 BufferDeleter deleter,
91 typedef std::list<Bucket *> BucketList;
95 static void DeleteBucket(Bucket *bucket);
97 class BucketVisitorCall
100 BucketVisitor *m_visitor;
103 BucketVisitorCall(BucketVisitor *visitor);
104 virtual ~BucketVisitorCall();
106 void operator()(Bucket *bucket) const;
111 * Construct empty binary queue
116 * Construct binary queue via bare copy of other binary queue
118 * @param[in] other Other binary queue to copy from
119 * @warning One cannot assume that bucket structure is preserved during copy
121 BinaryQueue(const BinaryQueue &other);
126 virtual ~BinaryQueue();
129 * Construct binary queue via bare copy of other binary queue
131 * @param[in] other Other binary queue to copy from
132 * @warning One cannot assume that bucket structure is preserved during copy
134 const BinaryQueue &operator=(const BinaryQueue &other);
137 * Append copy of @a bufferSize bytes from memory pointed by @a buffer
138 * to the end of binary queue. Uses default deleter based on free.
141 * @param[in] buffer Pointer to buffer to copy data from
142 * @param[in] bufferSize Number of bytes to copy
143 * @exception std::bad_alloc Cannot allocate memory to hold additional data
144 * @see BinaryQueue::BufferDeleterFree
146 void AppendCopy(const void *buffer, size_t bufferSize);
149 * Append @a bufferSize bytes from memory pointed by @a buffer
150 * to the end of binary queue. Uses custom provided deleter.
151 * Responsibility for deleting provided buffer is transfered to BinaryQueue.
154 * @param[in] buffer Pointer to data buffer
155 * @param[in] bufferSize Number of bytes available in buffer
156 * @param[in] deleter Pointer to deleter procedure used to free provided
158 * @param[in] userParam User parameter passed to deleter routine
159 * @exception std::bad_alloc Cannot allocate memory to hold additional data
161 void AppendUnmanaged(
164 BufferDeleter deleter =
165 &BinaryQueue::BufferDeleterFree,
166 void *userParam = nullptr);
169 * Append copy of other binary queue to the end of this binary queue
172 * @param[in] other Constant reference to other binary queue to copy data
174 * @exception std::bad_alloc Cannot allocate memory to hold additional data
175 * @warning One cannot assume that bucket structure is preserved during copy
177 void AppendCopyFrom(const BinaryQueue &other);
180 * Move bytes from other binary queue to the end of this binary queue.
181 * This also removes all bytes from other binary queue.
182 * This method is designed to be as fast as possible (only pointer swaps)
183 * and is suggested over making copies of binary queues.
184 * Bucket structure is preserved after operation.
187 * @param[in] other Reference to other binary queue to move data from
188 * @exception std::bad_alloc Cannot allocate memory to hold additional data
190 void AppendMoveFrom(BinaryQueue &other);
193 * Append copy of binary queue to the end of other binary queue
196 * @param[in] other Constant reference to other binary queue to copy data to
197 * @exception std::bad_alloc Cannot allocate memory to hold additional data
198 * @warning One cannot assume that bucket structure is preserved during copy
200 void AppendCopyTo(BinaryQueue &other) const;
203 * Move bytes from binary queue to the end of other binary queue.
204 * This also removes all bytes from binary queue.
205 * This method is designed to be as fast as possible (only pointer swaps)
206 * and is suggested over making copies of binary queues.
207 * Bucket structure is preserved after operation.
210 * @param[in] other Reference to other binary queue to move data to
211 * @exception std::bad_alloc Cannot allocate memory to hold additional data
213 void AppendMoveTo(BinaryQueue &other);
216 * Retrieve total size of all data contained in binary queue
218 * @return Number of bytes in binary queue
223 * Remove all data from binary queue
230 * Check if binary queue is empty
232 * @return true if binary queue is empty, false otherwise
237 * Remove @a size bytes from beginning of binary queue
240 * @param[in] size Number of bytes to remove
241 * @exception BinaryQueue::Exception::OutOfData Number of bytes is larger
242 * than available bytes in binary queue
244 void Consume(size_t size);
247 * Retrieve @a bufferSize bytes from beginning of binary queue and copy them
248 * to user supplied buffer
251 * @param[in] buffer Pointer to user buffer to receive bytes
252 * @param[in] bufferSize Size of user buffer pointed by @a buffer
253 * @exception BinaryQueue::Exception::OutOfData Number of bytes to flatten
254 * is larger than available bytes in binary queue
256 void Flatten(void *buffer, size_t bufferSize) const;
259 * Retrieve @a bufferSize bytes from beginning of binary queue, copy them
260 * to user supplied buffer, and remove from binary queue
263 * @param[in] buffer Pointer to user buffer to receive bytes
264 * @param[in] bufferSize Size of user buffer pointed by @a buffer
265 * @exception BinaryQueue::Exception::OutOfData Number of bytes to flatten
266 * is larger than available bytes in binary queue
268 void FlattenConsume(void *buffer, size_t bufferSize);
271 * Visit each buffer with data using visitor object
274 * @param[in] visitor Pointer to bucket visitor
275 * @see BinaryQueue::BucketVisitor
277 void VisitBuckets(BucketVisitor *visitor) const;
280 * IAbstractInput interface
282 virtual BinaryQueueAutoPtr Read(size_t size);
285 * IAbstractOutput interface
287 virtual size_t Write(const BinaryQueue &buffer, size_t bufferSize);
291 * Binary queue auto pointer
293 typedef std::auto_ptr<BinaryQueue> BinaryQueueAutoPtr;
296 #endif // DPL_BINARY_QUEUE_H