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>
34 * Binary stream implemented as constant size bucket list
36 * @todo Add optimized implementation for FlattenConsume
39 : public AbstractInputOutput
45 DECLARE_EXCEPTION_TYPE(DPL::Exception, Base)
46 DECLARE_EXCEPTION_TYPE(Base, OutOfData)
49 typedef void (*BufferDeleter)(const void *buffer, size_t bufferSize, void *userParam);
50 static void BufferDeleterFree(const void *buffer, size_t bufferSize, void *userParam);
58 virtual ~BucketVisitor();
64 * @param[in] buffer Constant pointer to bucket data buffer
65 * @param[in] bufferSize Number of bytes in bucket
67 virtual void OnVisitBucket(const void *buffer, size_t bufferSize) = 0;
79 BufferDeleter deleter;
82 Bucket(const void *buffer, size_t bufferSize, BufferDeleter deleter, void *userParam);
86 typedef std::list<Bucket *> BucketList;
90 static void DeleteBucket(Bucket *bucket);
92 class BucketVisitorCall
95 BucketVisitor *m_visitor;
98 BucketVisitorCall(BucketVisitor *visitor);
99 virtual ~BucketVisitorCall();
101 void operator()(Bucket *bucket) const;
106 * Construct empty binary queue
111 * Construct binary queue via bare copy of other binary queue
113 * @param[in] other Other binary queue to copy from
114 * @warning One cannot assume that bucket structure is preserved during copy
116 BinaryQueue(const BinaryQueue &other);
121 virtual ~BinaryQueue();
124 * Construct binary queue via bare copy of other binary queue
126 * @param[in] other Other binary queue to copy from
127 * @warning One cannot assume that bucket structure is preserved during copy
129 const BinaryQueue &operator=(const BinaryQueue &other);
132 * Append copy of @a bufferSize bytes from memory pointed by @a buffer
133 * to the end of binary queue. Uses default deleter based on free.
136 * @param[in] buffer Pointer to buffer to copy data from
137 * @param[in] bufferSize Number of bytes to copy
138 * @exception std::bad_alloc Cannot allocate memory to hold additional data
139 * @see BinaryQueue::BufferDeleterFree
141 void AppendCopy(const void *buffer, size_t bufferSize);
144 * Append @a bufferSize bytes from memory pointed by @a buffer
145 * to the end of binary queue. Uses custom provided deleter.
146 * Responsibility for deleting provided buffer is transfered to BinaryQueue.
149 * @param[in] buffer Pointer to data buffer
150 * @param[in] bufferSize Number of bytes available in buffer
151 * @param[in] deleter Pointer to deleter procedure used to free provided buffer
152 * @param[in] userParam User parameter passed to deleter routine
153 * @exception std::bad_alloc Cannot allocate memory to hold additional data
155 void AppendUnmanaged(const void *buffer, size_t bufferSize, BufferDeleter deleter = &BinaryQueue::BufferDeleterFree, void *userParam = NULL);
158 * Append copy of other binary queue to the end of this binary queue
161 * @param[in] other Constant reference to other binary queue to copy data from
162 * @exception std::bad_alloc Cannot allocate memory to hold additional data
163 * @warning One cannot assume that bucket structure is preserved during copy
165 void AppendCopyFrom(const BinaryQueue &other);
168 * Move bytes from other binary queue to the end of this binary queue.
169 * This also removes all bytes from other binary queue.
170 * This method is designed to be as fast as possible (only pointer swaps)
171 * and is suggested over making copies of binary queues.
172 * Bucket structure is preserved after operation.
175 * @param[in] other Reference to other binary queue to move data from
176 * @exception std::bad_alloc Cannot allocate memory to hold additional data
178 void AppendMoveFrom(BinaryQueue &other);
181 * Append copy of binary queue to the end of other binary queue
184 * @param[in] other Constant reference to other binary queue to copy data to
185 * @exception std::bad_alloc Cannot allocate memory to hold additional data
186 * @warning One cannot assume that bucket structure is preserved during copy
188 void AppendCopyTo(BinaryQueue &other) const;
191 * Move bytes from binary queue to the end of other binary queue.
192 * This also removes all bytes from binary queue.
193 * This method is designed to be as fast as possible (only pointer swaps)
194 * and is suggested over making copies of binary queues.
195 * Bucket structure is preserved after operation.
198 * @param[in] other Reference to other binary queue to move data to
199 * @exception std::bad_alloc Cannot allocate memory to hold additional data
201 void AppendMoveTo(BinaryQueue &other);
204 * Retrieve total size of all data contained in binary queue
206 * @return Number of bytes in binary queue
211 * Remove all data from binary queue
218 * Check if binary queue is empty
220 * @return true if binary queue is empty, false otherwise
225 * Remove @a size bytes from beginning of binary queue
228 * @param[in] size Number of bytes to remove
229 * @exception BinaryQueue::Exception::OutOfData Number of bytes is larger
230 * than available bytes in binary queue
232 void Consume(size_t size);
235 * Retrieve @a bufferSize bytes from beginning of binary queue and copy them
236 * to user supplied buffer
239 * @param[in] buffer Pointer to user buffer to receive bytes
240 * @param[in] bufferSize Size of user buffer pointed by @a buffer
241 * @exception BinaryQueue::Exception::OutOfData Number of bytes to flatten
242 * is larger than available bytes in binary queue
244 void Flatten(void *buffer, size_t bufferSize) const;
247 * Retrieve @a bufferSize bytes from beginning of binary queue, copy them
248 * to user supplied buffer, and remove from binary queue
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 FlattenConsume(void *buffer, size_t bufferSize);
259 * Visit each buffer with data using visitor object
262 * @param[in] visitor Pointer to bucket visitor
263 * @see BinaryQueue::BucketVisitor
265 void VisitBuckets(BucketVisitor *visitor) const;
268 * IAbstractInput interface
270 virtual BinaryQueueAutoPtr Read(size_t size);
273 * IAbstractOutput interface
275 virtual size_t Write(const BinaryQueue &buffer, size_t bufferSize);
279 * Binary queue auto pointer
281 typedef std::auto_ptr<BinaryQueue> BinaryQueueAutoPtr;
284 #endif // DPL_BINARY_QUEUE_H