tests/framework/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  * Binary stream implemented as constant size bucket list
  34  *
  35  * @todo Add optimized implementation for FlattenConsume
  36  */
  37 class BinaryQueue :
  38     public AbstractInputOutput
  39 {
  40   public:
  41     class Exception
  42     {
  43       public:
  44         DECLARE_EXCEPTION_TYPE(DPL::Exception, Base)
  45         DECLARE_EXCEPTION_TYPE(Base, OutOfData)
  46     };
  47
  48     typedef void (*BufferDeleter)(const void *buffer, size_t bufferSize,
  49                                   void *userParam);
  50     static void BufferDeleterFree(const void *buffer,
  51                                   size_t bufferSize,
  52                                   void *userParam);
  53
  54     class BucketVisitor
  55     {
  56       public:
  57         /**
  58          * Destructor
  59          */
  60         virtual ~BucketVisitor();
  61
  62         /**
  63          * Visit bucket
  64          *
  65          * @return none
  66          * @param[in] buffer Constant pointer to bucket data buffer
  67          * @param[in] bufferSize Number of bytes in bucket
  68          */
  69         virtual void OnVisitBucket(const void *buffer, size_t bufferSize) = 0;
  70     };
  71
  72   private:
  73     struct Bucket :
  74         private Noncopyable
  75     {
  76         const void *buffer;
  77         const void *ptr;
  78         size_t size;
  79         size_t left;
  80
  81         BufferDeleter deleter;
  82         void *param;
  83
  84         Bucket(const void *buffer,
  85                size_t bufferSize,
  86                BufferDeleter deleter,
  87                void *userParam);
  88         virtual ~Bucket();
  89     };
  90
  91     typedef std::list<Bucket *> BucketList;
  92     BucketList m_buckets;
  93     size_t m_size;
  94
  95     static void DeleteBucket(Bucket *bucket);
  96
  97     class BucketVisitorCall
  98     {
  99       private:
 100         BucketVisitor *m_visitor;
 101
 102       public:
 103         BucketVisitorCall(BucketVisitor *visitor);
 104         virtual ~BucketVisitorCall();
 105
 106         void operator()(Bucket *bucket) const;
 107     };
 108
 109   public:
 110     /**
 111      * Construct empty binary queue
 112      */
 113     BinaryQueue();
 114
 115     /**
 116      * Construct binary queue via bare copy of other binary queue
 117      *
 118      * @param[in] other Other binary queue to copy from
 119      * @warning One cannot assume that bucket structure is preserved during copy
 120      */
 121     BinaryQueue(const BinaryQueue &other);
 122
 123     /**
 124      * Destructor
 125      */
 126     virtual ~BinaryQueue();
 127
 128     /**
 129      * Construct binary queue via bare copy of other binary queue
 130      *
 131      * @param[in] other Other binary queue to copy from
 132      * @warning One cannot assume that bucket structure is preserved during copy
 133      */
 134     const BinaryQueue &operator=(const BinaryQueue &other);
 135
 136     /**
 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.
 139      *
 140      * @return none
 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
 145      */
 146     void AppendCopy(const void *buffer, size_t bufferSize);
 147
 148     /**
 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.
 152      *
 153      * @return none
 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
 157      * buffer
 158      * @param[in] userParam User parameter passed to deleter routine
 159      * @exception std::bad_alloc Cannot allocate memory to hold additional data
 160      */
 161     void AppendUnmanaged(
 162         const void *buffer,
 163         size_t bufferSize,
 164         BufferDeleter deleter =
 165             &BinaryQueue::BufferDeleterFree,
 166         void *userParam = nullptr);
 167
 168     /**
 169      * Append copy of other binary queue to the end of this binary queue
 170      *
 171      * @return none
 172      * @param[in] other Constant reference to other binary queue to copy data
 173      * from
 174      * @exception std::bad_alloc Cannot allocate memory to hold additional data
 175      * @warning One cannot assume that bucket structure is preserved during copy
 176      */
 177     void AppendCopyFrom(const BinaryQueue &other);
 178
 179     /**
 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.
 185      *
 186      * @return none
 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
 189      */
 190     void AppendMoveFrom(BinaryQueue &other);
 191
 192     /**
 193      * Append copy of binary queue to the end of other binary queue
 194      *
 195      * @return none
 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
 199      */
 200     void AppendCopyTo(BinaryQueue &other) const;
 201
 202     /**
 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.
 208      *
 209      * @return none
 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
 212      */
 213     void AppendMoveTo(BinaryQueue &other);
 214
 215     /**
 216      * Retrieve total size of all data contained in binary queue
 217      *
 218      * @return Number of bytes in binary queue
 219      */
 220     size_t Size() const;
 221
 222     /**
 223      * Remove all data from binary queue
 224      *
 225      * @return none
 226      */
 227     void Clear();
 228
 229     /**
 230      * Check if binary queue is empty
 231      *
 232      * @return true if binary queue is empty, false otherwise
 233      */
 234     bool Empty() const;
 235
 236     /**
 237      * Remove @a size bytes from beginning of binary queue
 238      *
 239      * @return none
 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
 243      */
 244     void Consume(size_t size);
 245
 246     /**
 247      * Retrieve @a bufferSize bytes from beginning of binary queue and copy them
 248      * to user supplied buffer
 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 Flatten(void *buffer, size_t bufferSize) const;
 257
 258     /**
 259      * Retrieve @a bufferSize bytes from beginning of binary queue, copy them
 260      * to user supplied buffer, and remove from binary queue
 261      *
 262      * @return none
 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
 267      */
 268     void FlattenConsume(void *buffer, size_t bufferSize);
 269
 270     /**
 271      * Visit each buffer with data using visitor object
 272      *
 273      * @return none
 274      * @param[in] visitor Pointer to bucket visitor
 275      * @see BinaryQueue::BucketVisitor
 276      */
 277     void VisitBuckets(BucketVisitor *visitor) const;
 278
 279     /**
 280      * IAbstractInput interface
 281      */
 282     virtual BinaryQueueAutoPtr Read(size_t size);
 283
 284     /**
 285      * IAbstractOutput interface
 286      */
 287     virtual size_t Write(const BinaryQueue &buffer, size_t bufferSize);
 288 };
 289
 290 /**
 291  * Binary queue auto pointer
 292  */
 293 typedef std::auto_ptr<BinaryQueue> BinaryQueueAutoPtr;
 294 } // namespace DPL
 295
 296 #endif // DPL_BINARY_QUEUE_H