modules/core/include/dpl/binary_queue.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16 /*
  17  * @file        binary_queue.h
  18  * @author      Przemyslaw Dobrowolski (p.dobrowolsk@samsung.com)
  19  * @version     1.0
  20  * @brief       This file is the header file of binary queue
  21  */
  22 #ifndef DPL_BINARY_QUEUE_H
  23 #define DPL_BINARY_QUEUE_H
  24
  25 #include <dpl/abstract_input_output.h>
  26 #include <dpl/exception.h>
  27 #include <dpl/noncopyable.h>
  28 #include <memory>
  29 #include <list>
  30
  31 namespace DPL
  32 {
  33 /**
  34  * Binary stream implemented as constant size bucket list
  35  *
  36  * @todo Add optimized implementation for FlattenConsume
  37  */
  38 class BinaryQueue
  39     : public AbstractInputOutput
  40 {
  41 public:
  42     class Exception
  43     {
  44     public:
  45         DECLARE_EXCEPTION_TYPE(DPL::Exception, Base)
  46         DECLARE_EXCEPTION_TYPE(Base, OutOfData)
  47     };
  48
  49     typedef void (*BufferDeleter)(const void *buffer, size_t bufferSize, void *userParam);
  50     static void BufferDeleterFree(const void *buffer, size_t bufferSize, void *userParam);
  51
  52     class BucketVisitor
  53     {
  54     public:
  55         /**
  56          * Destructor
  57          */
  58         virtual ~BucketVisitor();
  59
  60         /**
  61          * Visit bucket
  62          *
  63          * @return none
  64          * @param[in] buffer Constant pointer to bucket data buffer
  65          * @param[in] bufferSize Number of bytes in bucket
  66          */
  67         virtual void OnVisitBucket(const void *buffer, size_t bufferSize) = 0;
  68     };
  69
  70 private:
  71     struct Bucket
  72         : private Noncopyable
  73     {
  74         const void *buffer;
  75         const void *ptr;
  76         size_t size;
  77         size_t left;
  78
  79         BufferDeleter deleter;
  80         void *param;
  81
  82         Bucket(const void *buffer, size_t bufferSize, BufferDeleter deleter, void *userParam);
  83         virtual ~Bucket();
  84     };
  85
  86     typedef std::list<Bucket *> BucketList;
  87     BucketList m_buckets;
  88     size_t m_size;
  89
  90     static void DeleteBucket(Bucket *bucket);
  91
  92     class BucketVisitorCall
  93     {
  94     private:
  95         BucketVisitor *m_visitor;
  96
  97     public:
  98         BucketVisitorCall(BucketVisitor *visitor);
  99         virtual ~BucketVisitorCall();
 100
 101         void operator()(Bucket *bucket) const;
 102     };
 103
 104 public:
 105     /**
 106      * Construct empty binary queue
 107      */
 108     BinaryQueue();
 109
 110     /**
 111      * Construct binary queue via bare copy of other binary queue
 112      *
 113      * @param[in] other Other binary queue to copy from
 114      * @warning One cannot assume that bucket structure is preserved during copy
 115      */
 116     BinaryQueue(const BinaryQueue &other);
 117
 118     /**
 119      * Destructor
 120      */
 121     virtual ~BinaryQueue();
 122
 123     /**
 124      * Construct binary queue via bare copy of other binary queue
 125      *
 126      * @param[in] other Other binary queue to copy from
 127      * @warning One cannot assume that bucket structure is preserved during copy
 128      */
 129     const BinaryQueue &operator=(const BinaryQueue &other);
 130
 131     /**
 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.
 134      *
 135      * @return none
 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
 140      */
 141     void AppendCopy(const void *buffer, size_t bufferSize);
 142
 143     /**
 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.
 147      *
 148      * @return none
 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
 154      */
 155     void AppendUnmanaged(const void *buffer, size_t bufferSize, BufferDeleter deleter = &BinaryQueue::BufferDeleterFree, void *userParam = NULL);
 156
 157     /**
 158      * Append copy of other binary queue to the end of this binary queue
 159      *
 160      * @return none
 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
 164      */
 165     void AppendCopyFrom(const BinaryQueue &other);
 166
 167     /**
 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.
 173      *
 174      * @return none
 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
 177      */
 178     void AppendMoveFrom(BinaryQueue &other);
 179
 180     /**
 181      * Append copy of binary queue to the end of other binary queue
 182      *
 183      * @return none
 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
 187      */
 188     void AppendCopyTo(BinaryQueue &other) const;
 189
 190     /**
 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.
 196      *
 197      * @return none
 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
 200      */
 201     void AppendMoveTo(BinaryQueue &other);
 202
 203     /**
 204      * Retrieve total size of all data contained in binary queue
 205      *
 206      * @return Number of bytes in binary queue
 207      */
 208     size_t Size() const;
 209
 210     /**
 211      * Remove all data from binary queue
 212      *
 213      * @return none
 214      */
 215     void Clear();
 216
 217     /**
 218      * Check if binary queue is empty
 219      *
 220      * @return true if binary queue is empty, false otherwise
 221      */
 222     bool Empty() const;
 223
 224     /**
 225      * Remove @a size bytes from beginning of binary queue
 226      *
 227      * @return none
 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
 231      */
 232     void Consume(size_t size);
 233
 234     /**
 235      * Retrieve @a bufferSize bytes from beginning of binary queue and copy them
 236      * to user supplied buffer
 237      *
 238      * @return none
 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
 243      */
 244     void Flatten(void *buffer, size_t bufferSize) const;
 245
 246     /**
 247      * Retrieve @a bufferSize bytes from beginning of binary queue, copy them
 248      * to user supplied buffer, and remove from binary queue
 249      *
 250      * @return none
 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
 255      */
 256     void FlattenConsume(void *buffer, size_t bufferSize);
 257
 258     /**
 259      * Visit each buffer with data using visitor object
 260      *
 261      * @return none
 262      * @param[in] visitor Pointer to bucket visitor
 263      * @see BinaryQueue::BucketVisitor
 264      */
 265     void VisitBuckets(BucketVisitor *visitor) const;
 266
 267     /**
 268      * IAbstractInput interface
 269      */
 270     virtual BinaryQueueAutoPtr Read(size_t size);
 271
 272     /**
 273      * IAbstractOutput interface
 274      */
 275     virtual size_t Write(const BinaryQueue &buffer, size_t bufferSize);
 276 };
 277
 278 /**
 279  * Binary queue auto pointer
 280  */
 281 typedef std::auto_ptr<BinaryQueue> BinaryQueueAutoPtr;
 282 } // namespace DPL
 283
 284 #endif // DPL_BINARY_QUEUE_H