src/manager/dpl/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 CENT_KEY_BINARY_QUEUE_H
  23 #define CENT_KEY_BINARY_QUEUE_H
  24
  25 //#include <dpl/abstract_input_output.h>
  26 #include <dpl/exception.h>
  27 #include <memory>
  28 #include <list>
  29 #include <symbol-visibility.h>
  30 #include <noncopyable.h>
  31
  32 namespace CKM {
  33 /**
  34  * Binary queue auto pointer
  35  */
  36 class BinaryQueue;
  37 using BinaryQueueUniquePtr = std::unique_ptr<BinaryQueue>;
  38
  39 /**
  40  * Binary stream implemented as constant size bucket list
  41  *
  42  * @todo Add optimized implementation for FlattenConsume
  43  */
  44 class COMMON_API BinaryQueue {
  45         //  : public AbstractInputOutput
  46 public:
  47         class Exception {
  48         public:
  49                 DECLARE_EXCEPTION_TYPE(CKM::Exception, Base)
  50                 DECLARE_EXCEPTION_TYPE(Base, OutOfData)
  51         };
  52
  53         typedef void (*BufferDeleter)(const void *buffer, size_t bufferSize,
  54                                                                   void *userParam);
  55         static void BufferDeleterFree(const void *buffer,
  56                                                                   size_t bufferSize,
  57                                                                   void *userParam);
  58
  59         class BucketVisitor {
  60         public:
  61                 /**
  62                  * Destructor
  63                  */
  64                 virtual ~BucketVisitor();
  65
  66                 /**
  67                  * Visit bucket
  68                  *
  69                  * @return none
  70                  * @param[in] buffer Constant pointer to bucket data buffer
  71                  * @param[in] bufferSize Number of bytes in bucket
  72                  */
  73                 virtual void OnVisitBucket(const void *buffer, size_t bufferSize) = 0;
  74         };
  75
  76 private:
  77         struct Bucket {
  78                 NONCOPYABLE(Bucket);
  79
  80                 const void *buffer;
  81                 const void *ptr;
  82                 size_t size;
  83                 size_t left;
  84
  85                 BufferDeleter deleter;
  86                 void *param;
  87
  88                 Bucket(const void *buffer,
  89                            size_t bufferSize,
  90                            BufferDeleter deleter,
  91                            void *userParam);
  92                 virtual ~Bucket();
  93         };
  94
  95         typedef std::list<Bucket *> BucketList;
  96         BucketList m_buckets;
  97         size_t m_size;
  98
  99         static void DeleteBucket(Bucket *bucket);
 100
 101         class BucketVisitorCall {
 102         private:
 103                 BucketVisitor *m_visitor;
 104
 105         public:
 106                 BucketVisitorCall(BucketVisitor *visitor);
 107                 virtual ~BucketVisitorCall();
 108
 109                 void operator()(Bucket *bucket) const;
 110         };
 111
 112 public:
 113         /**
 114          * Construct empty binary queue
 115          */
 116         BinaryQueue();
 117
 118         /**
 119          * Construct binary queue via bare copy of other binary queue
 120          *
 121          * @param[in] other Other binary queue to copy from
 122          * @warning One cannot assume that bucket structure is preserved during copy
 123          */
 124         BinaryQueue(const BinaryQueue &other);
 125
 126         /**
 127          * Construct binary queue by moving data from other binary queue
 128          *
 129          * @param[in] other Other binary queue to move from
 130          */
 131         BinaryQueue(BinaryQueue &&) = default;
 132
 133         /**
 134          * Destructor
 135          */
 136         virtual ~BinaryQueue();
 137
 138         /**
 139          * Construct binary queue via bare copy of other binary queue
 140          *
 141          * @param[in] other Other binary queue to copy from
 142          * @warning One cannot assume that bucket structure is preserved during copy
 143          */
 144         const BinaryQueue &operator=(const BinaryQueue &other);
 145
 146         /**
 147          * Assign data from other binary queue using move semantics
 148          *
 149          * @param[in] other Other binary queue to move from
 150          */
 151         BinaryQueue &operator=(BinaryQueue &&) = default;
 152
 153         /**
 154          * Append copy of @a bufferSize bytes from memory pointed by @a buffer
 155          * to the end of binary queue. Uses default deleter based on free.
 156          *
 157          * @return none
 158          * @param[in] buffer Pointer to buffer to copy data from
 159          * @param[in] bufferSize Number of bytes to copy
 160          * @exception std::bad_alloc Cannot allocate memory to hold additional data
 161          * @see BinaryQueue::BufferDeleterFree
 162          */
 163         void AppendCopy(const void *buffer, size_t bufferSize);
 164
 165         /**
 166          * Append @a bufferSize bytes from memory pointed by @a buffer
 167          * to the end of binary queue. Uses custom provided deleter.
 168          * Responsibility for deleting provided buffer is transfered to BinaryQueue.
 169          *
 170          * @return none
 171          * @param[in] buffer Pointer to data buffer
 172          * @param[in] bufferSize Number of bytes available in buffer
 173          * @param[in] deleter Pointer to deleter procedure used to free provided
 174          * buffer
 175          * @param[in] userParam User parameter passed to deleter routine
 176          * @exception std::bad_alloc Cannot allocate memory to hold additional data
 177          */
 178         void AppendUnmanaged(
 179                 const void *buffer,
 180                 size_t bufferSize,
 181                 BufferDeleter deleter =
 182                         &BinaryQueue::BufferDeleterFree,
 183                 void *userParam = NULL);
 184
 185         /**
 186          * Append copy of other binary queue to the end of this binary queue
 187          *
 188          * @return none
 189          * @param[in] other Constant reference to other binary queue to copy data
 190          * from
 191          * @exception std::bad_alloc Cannot allocate memory to hold additional data
 192          * @warning One cannot assume that bucket structure is preserved during copy
 193          */
 194         void AppendCopyFrom(const BinaryQueue &other);
 195
 196         /**
 197          * Move bytes from other binary queue to the end of this binary queue.
 198          * This also removes all bytes from other binary queue.
 199          * This method is designed to be as fast as possible (only pointer swaps)
 200          * and is suggested over making copies of binary queues.
 201          * Bucket structure is preserved after operation.
 202          *
 203          * @return none
 204          * @param[in] other Reference to other binary queue to move data from
 205          * @exception std::bad_alloc Cannot allocate memory to hold additional data
 206          */
 207         void AppendMoveFrom(BinaryQueue &other);
 208
 209         /**
 210          * Append copy of binary queue to the end of other binary queue
 211          *
 212          * @return none
 213          * @param[in] other Constant reference to other binary queue to copy data to
 214          * @exception std::bad_alloc Cannot allocate memory to hold additional data
 215          * @warning One cannot assume that bucket structure is preserved during copy
 216          */
 217         void AppendCopyTo(BinaryQueue &other) const;
 218
 219         /**
 220          * Move bytes from binary queue to the end of other binary queue.
 221          * This also removes all bytes from binary queue.
 222          * This method is designed to be as fast as possible (only pointer swaps)
 223          * and is suggested over making copies of binary queues.
 224          * Bucket structure is preserved after operation.
 225          *
 226          * @return none
 227          * @param[in] other Reference to other binary queue to move data to
 228          * @exception std::bad_alloc Cannot allocate memory to hold additional data
 229          */
 230         void AppendMoveTo(BinaryQueue &other);
 231
 232         /**
 233          * Retrieve total size of all data contained in binary queue
 234          *
 235          * @return Number of bytes in binary queue
 236          */
 237         size_t Size() const;
 238
 239         /**
 240          * Remove all data from binary queue
 241          *
 242          * @return none
 243          */
 244         void Clear();
 245
 246         /**
 247          * Check if binary queue is empty
 248          *
 249          * @return true if binary queue is empty, false otherwise
 250          */
 251         bool Empty() const;
 252
 253         /**
 254          * Remove @a size bytes from beginning of binary queue
 255          *
 256          * @return none
 257          * @param[in] size Number of bytes to remove
 258          * @exception BinaryQueue::Exception::OutOfData Number of bytes is larger
 259          *            than available bytes in binary queue
 260          */
 261         void Consume(size_t size);
 262
 263         /**
 264          * Retrieve @a bufferSize bytes from beginning of binary queue and copy them
 265          * to user supplied buffer
 266          *
 267          * @return none
 268          * @param[in] buffer Pointer to user buffer to receive bytes
 269          * @param[in] bufferSize Size of user buffer pointed by @a buffer
 270          * @exception BinaryQueue::Exception::OutOfData Number of bytes to flatten
 271          *            is larger than available bytes in binary queue
 272          */
 273         void Flatten(void *buffer, size_t bufferSize) const;
 274
 275         /**
 276          * Retrieve @a bufferSize bytes from beginning of binary queue, copy them
 277          * to user supplied buffer, and remove from binary queue
 278          *
 279          * @return none
 280          * @param[in] buffer Pointer to user buffer to receive bytes
 281          * @param[in] bufferSize Size of user buffer pointed by @a buffer
 282          * @exception BinaryQueue::Exception::OutOfData Number of bytes to flatten
 283          *            is larger than available bytes in binary queue
 284          */
 285         void FlattenConsume(void *buffer, size_t bufferSize);
 286
 287         /**
 288          * Visit each buffer with data using visitor object
 289          *
 290          * @return none
 291          * @param[in] visitor Pointer to bucket visitor
 292          * @see BinaryQueue::BucketVisitor
 293          */
 294         void VisitBuckets(BucketVisitor *visitor) const;
 295
 296         /**
 297          * IAbstractInput interface
 298          */
 299         virtual BinaryQueueUniquePtr Read(size_t size);
 300
 301         /**
 302          * IAbstractOutput interface
 303          */
 304         virtual size_t Write(const BinaryQueue &buffer, size_t bufferSize);
 305 };
 306
 307 } // namespace CKM
 308
 309 #endif // CENT_KEY_BINARY_QUEUE_H