include/wvbufbase.h

   1 /* -*- Mode: C++ -*-
   2  * Worldvisions Weaver Software:
   3  *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
   4  *
   5  * A generic buffering API.
   6  * Please declare specializations in a separate header file,
   7  * See "wvbuf.h".
   8  */
   9 #ifndef __WVBUFFERBASE_H
  10 #define __WVBUFFERBASE_H
  11
  12 #include "wvbufstore.h"
  13
  14 template<class T>
  15 class WvBufBase;
  16
  17 /**
  18  * An abstract generic buffer template.
  19  * Buffers are simple data queues designed to ease the construction of
  20  * functions that must generate, consume, or transform large amount of
  21  * data in pipeline fashion.  Concrete buffer subclases define the actual
  22  * storage mechanism and queuing machinery.  In addition they may provide
  23  * additional functionality for accomplishing particular tasks.
  24  *
  25  * The base component is split into two parts, WvBufBaseCommonImpl
  26  * that defines the common API for all buffer types, and WvBufBase
  27  * that allows specializations to be defined to add functionality
  28  * to the base type.  When passing around buffer objects, you should
  29  * use the WvBufBase<T> type rather than WvBufBaseCommonImpl<T>.
  30  *
  31  * See WvBufBase<T>
  32  * "T" is the type of object to store, must be a primitive or a struct
  33  *        without special initialization, copy, or assignment semantics
  34  */
  35 template<class T>
  36 class WvBufBaseCommonImpl
  37 {
  38 protected:
  39     typedef T Elem;
  40     typedef WvBufBase<T> Buffer;
  41
  42     WvBufStore *store;
  43
  44     // discourage copying
  45     explicit WvBufBaseCommonImpl(
  46         const WvBufBaseCommonImpl &other) { }
  47
  48 protected:
  49     /**
  50      * Initializes the buffer.
  51      *
  52      * Note: Does not take ownership of the storage object.
  53      *
  54      *
  55      * "store" is the low-level storage object
  56      */
  57     explicit WvBufBaseCommonImpl(WvBufStore *store) :
  58         store(store) { }
  59
  60 public:
  61     /** Destroys the buffer. */
  62     virtual ~WvBufBaseCommonImpl() { }
  63
  64     /**
  65      * Returns a pointer to the underlying storage class object.
  66      *
  67      * Returns: the low-level storage class object pointer, non-null
  68      */
  69     WvBufStore *getstore()
  70     {
  71         return store;
  72     }
  73
  74     /*** Buffer Reading ***/
  75
  76     /**
  77      * Returns true if the buffer supports reading.
  78      *
  79      * Returns: true if reading is supported
  80      */
  81     bool isreadable() const
  82     {
  83         return store->isreadable();
  84     }
  85
  86     /**
  87      * Returns the number of elements in the buffer currently
  88      * available for reading.
  89      *
  90      * This function could also be called gettable().
  91      */
  92     size_t used() const
  93     {
  94         return store->used() / sizeof(Elem);
  95     }
  96
  97     /**
  98      * Reads exactly the specified number of elements and returns
  99      * a pointer to a storage location owned by the buffer.
 100      *
 101      * The pointer is only valid until the next non-const buffer
 102      * member is called. eg. alloc(size_t)
 103      *
 104      * If count == 0, a NULL pointer may be returned.
 105      *
 106      * It is an error for count to be greater than the number of
 107      * available elements in the buffer.
 108      *
 109      * For maximum efficiency, call this function multiple times
 110      * with count no greater than optgettable() each time.
 111      *
 112      * After this operation, at least count elements may be ungotten.
 113      */
 114     const T *get(size_t count)
 115     {
 116         if (count > used())
 117             return NULL;
 118
 119         return static_cast<const T*>(
 120             store->get(count * sizeof(Elem)));
 121     }
 122
 123     /**
 124      * Skips exactly the specified number of elements.
 125      *
 126      * This is equivalent to invoking get(size_t) with the count
 127      * and discarding the result, but may be faster for certain
 128      * types of buffers.  As with get(size_t), the call may be
 129      * followed up by an unget(size_t).
 130      *
 131      * It is an error for count to be greater than the number of
 132      * available elements in the buffer.
 133      *
 134      * "count" is the number of elements
 135      */
 136     void skip(size_t count)
 137     {
 138         store->skip(count * sizeof(Elem));
 139     }
 140
 141     /**
 142      * Returns the optimal maximum number of elements in the
 143      * buffer currently available for reading without incurring
 144      * significant overhead.
 145      *
 146      * Invariants:
 147      *
 148      *  - optgettable() <= used()
 149      *  - optgettable() != 0 if used() != 0
 150      *
 151      *
 152      * Returns: the number of elements
 153      */
 154     size_t optgettable() const
 155     {
 156         size_t avail = store->optgettable();
 157         size_t elems = avail / sizeof(Elem);
 158         if (elems != 0) return elems;
 159         return avail != 0 && store->used() >= sizeof(Elem) ? 1 : 0;
 160     }
 161
 162     /**
 163      * Ungets exactly the specified number of elements by returning
 164      * them to the buffer for subsequent reads.
 165      *
 166      * This operation may always be safely performed with count
 167      * less than or equal to that specified in the last get(size_t)
 168      * if no non-const buffer members have been called since then.
 169      *
 170      * If count == 0, nothing happens.
 171      *
 172      * It is an error for count to be greater than ungettable().
 173      *
 174      *
 175      * "count" is the number of elements
 176      */
 177     void unget(size_t count)
 178     {
 179         store->unget(count * sizeof(Elem));
 180     }
 181
 182     /**
 183      * Returns the maximum number of elements that may be ungotten
 184      * at this time.
 185      *
 186      * Returns: the number of elements
 187      */
 188     size_t ungettable() const
 189     {
 190         return store->ungettable() / sizeof(Elem);
 191     }
 192
 193     /**
 194      * Returns a const pointer into the buffer at the specified
 195      * offset to the specified number of elements without actually
 196      * adjusting the current get() index.
 197      *
 198      * The pointer is only valid until the next non-const buffer
 199      * member is called. eg. alloc(size_t)
 200      *
 201      * If count == 0, a NULL pointer may be returned.
 202      *
 203      * If offset is greater than zero, then elements will be returned
 204      * beginning with the with the offset'th element that would be
 205      * returned by get(size_t).
 206      *
 207      * If offset equals zero, then elements will be returned beginning
 208      * with the next one available for get(size_t).
 209      *
 210      * If offset is less than zero, then elements will be returned
 211      * beginning with the first one that would be returned on a
 212      * get(size_t) following an unget(-offset).
 213      *
 214      * It is an error for count to be greater than peekable(offset).
 215      *
 216      * For maximum efficiency, call this function multiple times
 217      * with count no greater than that returned by optpeekable(size_t)
 218      * at incremental offsets.
 219      *
 220      *
 221      * "offset" is the buffer offset
 222      * "count" is the number of elements
 223      * Returns: the element storage pointer
 224      */
 225     const T *peek(int offset, size_t count)
 226     {
 227         return static_cast<const T*>(store->peek(
 228             offset * sizeof(Elem), count * sizeof(Elem)));
 229     }
 230
 231     size_t peekable(int offset)
 232     {
 233         return store->peekable(offset * sizeof(Elem)) / sizeof(Elem);
 234     }
 235
 236     size_t optpeekable(int offset)
 237     {
 238         offset *= sizeof(Elem);
 239         size_t avail = store->optpeekable(offset);
 240         size_t elems = avail / sizeof(Elem);
 241         if (elems != 0) return elems;
 242         return avail != 0 &&
 243             store->peekable(offset) >= sizeof(Elem) ? 1 : 0;
 244     }
 245
 246     /**
 247      * Clears the buffer.
 248      *
 249      * For many types of buffers, calling zap() will increased the
 250      * amount of free space available for writing (see below) by
 251      * an amount greater than used().  Hence it is wise to zap()
 252      * a buffer just before writing to it to maximize free space.
 253      *
 254      * After this operation, used() == 0, and often ungettable() == 0.
 255      *
 256      */
 257     void zap()
 258     {
 259         store->zap();
 260     }
 261
 262     /**
 263      * Reads the next element from the buffer.
 264      *
 265      * It is an error to invoke this method if used() == 0.
 266      *
 267      * After this operation, at least 1 element may be ungotten.
 268      *
 269      *
 270      * Returns: the element
 271      */
 272     T get()
 273     {
 274         return *get(1);
 275     }
 276
 277     /**
 278      * Returns the element at the specified offset in the buffer.
 279      *
 280      * It is an error to invoke this method if used() == 0.
 281      *
 282      *
 283      * "offset" is the offset, default 0
 284      * Returns: the element
 285      */
 286     T peek(int offset = 0)
 287     {
 288         return *peek(offset * sizeof(Elem), sizeof(Elem));
 289     }
 290
 291     /**
 292      * Efficiently copies the specified number of elements from the
 293      * buffer to the specified UNINITIALIZED storage location
 294      * and removes the elements from the buffer.
 295      *
 296      * It is an error for count to be greater than used().
 297      *
 298      * For maximum efficiency, choose as large a count as possible.
 299      *
 300      * The pointer buf may be NULL only if count == 0.
 301      *
 302      * After this operation, an indeterminate number of elements
 303      * may be ungotten.
 304      *
 305      *
 306      * "buf" is the buffer that will receive the elements
 307      * "count" is the number of elements
 308      */
 309     void move(T *buf, size_t count)
 310     {
 311         store->move(buf, count * sizeof(Elem));
 312     }
 313
 314     /**
 315      * Efficiently copies the specified number of elements from the
 316      * buffer to the specified UNINITIALIZED storage location
 317      * but does not remove the elements from the buffer.
 318      *
 319      * It is an error for count to be greater than peekable(offset).
 320      *
 321      * For maximum efficiency, choose as large a count as possible.
 322      *
 323      * The pointer buf may be NULL only if count == 0.
 324      *
 325      *
 326      * "buf" is the buffer that will receive the elements
 327      * "offset" is the buffer offset
 328      * "count" is the number of elements
 329      */
 330     void copy(T *buf, int offset, size_t count)
 331     {
 332         store->copy(buf, offset * sizeof(Elem), count * sizeof(Elem));
 333     }
 334
 335     /*** Buffer Writing ***/
 336
 337     /**
 338      * Returns true if the buffer supports writing.
 339      *
 340      * Returns: true if writing is supported
 341      */
 342     bool iswritable() const
 343     {
 344         return true;
 345     }
 346
 347     /**
 348      * Returns the number of elements that the buffer can currently
 349      * accept for writing.
 350      *
 351      * Returns: the number of elements
 352      */
 353     size_t free() const
 354     {
 355         return store->free() / sizeof(Elem);
 356     }
 357
 358     /**
 359      * Allocates exactly the specified number of elements and returns
 360      * a pointer to an UNINITIALIZED storage location owned by the
 361      * buffer.
 362      *
 363      * The pointer is only valid until the next non-const buffer
 364      * member is called. eg. alloc(size_t)
 365      *
 366      * If count == 0, a NULL pointer may be returned.
 367      *
 368      * It is an error for count to be greater than free().
 369      *
 370      * For best results, call this function multiple times with
 371      * count no greater than optallocable() each time.
 372      *
 373      * After this operation, at least count elements may be unallocated.
 374      *
 375      *
 376      * "count" is the number of elements
 377      * Returns: the element storage pointer
 378      */
 379     T *alloc(size_t count)
 380     {
 381         return static_cast<T*>(store->alloc(count * sizeof(Elem)));
 382     }
 383
 384     /**
 385      * Returns the optimal maximum number of elements that the
 386      * buffer can currently accept for writing without incurring
 387      * significant overhead.
 388      *
 389      * Invariants:
 390      *
 391      *  - optallocable() <= free()
 392      *  - optallocable() != 0 if free() != 0
 393      *
 394      *
 395      * Returns: the number of elements
 396      */
 397     size_t optallocable() const
 398     {
 399         size_t avail = store->optallocable();
 400         size_t elems = avail / sizeof(Elem);
 401         if (elems != 0) return elems;
 402         return avail != 0 && store->free() >= sizeof(Elem) ? 1 : 0;
 403     }
 404
 405     /**
 406      * Unallocates exactly the specified number of elements by removing
 407      * them from the buffer and releasing their storage.
 408      *
 409      * This operation may always be safely performed with count
 410      * less than or equal to that specified in the last alloc(size_t)
 411      * or put(const T*, size_t) if no non-const buffer members have
 412      * been called since then.
 413      *
 414      * If count == 0, nothing happens.
 415      *
 416      * It is an error for count to be greater than unallocable().
 417      *
 418      *
 419      * "count" is the number of elements
 420      */
 421     void unalloc(size_t count)
 422     {
 423         return store->unalloc(count * sizeof(Elem));
 424     }
 425
 426     /**
 427      * Returns the maximum number of elements that may be unallocated
 428      * at this time.
 429      *
 430      * For all practical purposes, this number will always be at least
 431      * as large as the amount currently in use.  It is provided
 432      * primarily for symmetry, but also to handle cases where
 433      * buffer reading (hence used()) is not supported by the
 434      * implementation.
 435      *
 436      * Invariants:
 437      *
 438      *  - unallocable() >= used()
 439      *
 440      *
 441      * Returns: the number of elements
 442      */
 443     size_t unallocable() const
 444     {
 445         return store->unallocable() / sizeof(Elem);
 446     }
 447
 448     /**
 449      * Returns a non-const pointer info the buffer at the specified
 450      * offset to the specified number of elements without actually
 451      * adjusting the current get() index.
 452      *
 453      * Other than the fact that the returned storage is mutable,
 454      * operates identically to peek(int, size_t).
 455      *
 456      *
 457      * "offset" is the buffer offset
 458      * "count" is the number of elements
 459      * Returns: the element storage pointer
 460      */
 461     T *mutablepeek(int offset, size_t count)
 462     {
 463         return static_cast<T*>(store->mutablepeek(
 464             offset * sizeof(Elem), count * sizeof(Elem)));
 465     }
 466
 467     /**
 468      * Writes the specified number of elements from the specified
 469      * storage location into the buffer at its tail.
 470      *
 471      * It is an error for count to be greater than free().
 472      *
 473      * For maximum efficiency, choose as large a count as possible.
 474      *
 475      * The pointer buf may be NULL only if count == 0.
 476      *
 477      * After this operation, at least count elements may be unallocated.
 478      *
 479      *
 480      * "data" is the buffer that contains the elements
 481      * "count" is the number of elements
 482      */
 483     void put(const T *data, size_t count)
 484     {
 485         store->put(data, count * sizeof(Elem));
 486     }
 487
 488     /**
 489      * Efficiently copies the specified number of elements from the
 490      * specified storage location into the buffer at a particular
 491      * offset.
 492      *
 493      * If offset <= used() and offset + count > used(), the
 494      * remaining data is simply tacked onto the end of the buffer
 495      * with put().
 496      *
 497      * It is an error for count to be greater than free() - offset.
 498      *
 499      *
 500      * "data" is the buffer that contains the elements
 501      * "count" is the number of elements
 502      * "offset" is the buffer offset, default 0
 503      */
 504     void poke(const T *data, int offset, size_t count)
 505     {
 506         store->poke(data, offset * sizeof(Elem), count * sizeof(Elem));
 507     }
 508
 509     /**
 510      * Writes the element into the buffer at its tail.
 511      *
 512      * It is an error to invoke this method if free() == 0.
 513      *
 514      * After this operation, at least 1 element may be unallocated.
 515      *
 516      *
 517      * "valid" is the element
 518      */
 519     void put(T &value)
 520     {
 521         store->fastput(& value, sizeof(Elem));
 522     }
 523
 524     /**
 525      * Writes the element into the buffer at the specified offset.
 526      *
 527      * It is an error to invoke this method if free() == 0.
 528      *
 529      * After this operation, at least 1 element may be unallocated.
 530      *
 531      *
 532      * "value" is the element
 533      * "offset" is the buffer offset
 534      */
 535     void poke(T &value, int offset)
 536     {
 537         poke(& value, offset, 1);
 538     }
 539
 540
 541     /*** Buffer to Buffer Transfers ***/
 542
 543     /**
 544      * Efficiently moves count bytes from the specified buffer into
 545      * this one.  In some cases, this may be a zero-copy operation.
 546      *
 547      * It is an error for count to be greater than inbuf.used().
 548      *
 549      * For maximum efficiency, choose as large a count as possible.
 550      *
 551      * After this operation, an indeterminate number of elements
 552      * may be ungotten from inbuf.
 553      *
 554      *
 555      * "inbuf" is the buffer from which to read
 556      * "count" is the number of elements
 557      */
 558     void merge(Buffer &inbuf, size_t count)
 559     {
 560         store->merge(*inbuf.store, count * sizeof(Elem));
 561     }
 562
 563     /**
 564      * Efficiently merges the entire contents of a buffer into this one.
 565      *
 566      * "inbuf" is the buffer from which to read
 567      */
 568     void merge(Buffer &inbuf)
 569     {
 570         merge(inbuf, inbuf.used());
 571     }
 572 };
 573
 574
 575
 576 /**
 577  * The generic buffer base type.
 578  * To specialize buffers to add new functionality, declare a template
 579  * specialization of this type that derives from WvBufBaseCommonImpl.
 580  *
 581  * See WvBufBaseCommonImpl<T>
 582  * "T" is the type of object to store, must be a primitive or a struct
 583  *        without special initialization, copy, or assignment semantics
 584  */
 585 template<class T>
 586 class WvBufBase : public WvBufBaseCommonImpl<T>
 587 {
 588 public:
 589     explicit WvBufBase(WvBufStore *store) :
 590         WvBufBaseCommonImpl<T>(store) { }
 591 };
 592
 593
 594
 595 /**
 596  * A buffer that wraps a pre-allocated array and provides
 597  * read-write access to its elements.
 598  *
 599  * "T" is the type of object to store, must be a primitive or a struct
 600  *        without special initialization, copy, or assignment semantics
 601  */
 602 template<class T>
 603 class WvInPlaceBufBase : public WvBufBase<T>
 604 {
 605 protected:
 606     typedef T Elem;
 607
 608     WvInPlaceBufStore mystore;
 609
 610 public:
 611     /**
 612      * Creates a new buffer backed by the supplied array.
 613      *
 614      * "_data" is the array of data to wrap
 615      * "_avail" is the amount of data available for reading
 616      * "_size" is the size of the array
 617      * "_autofree" is if true, the array will be freed when discarded
 618      */
 619     WvInPlaceBufBase(T *_data, size_t _avail, size_t _size,
 620         bool _autofree = false) :
 621         WvBufBase<T>(& mystore),
 622         mystore(sizeof(Elem), _data, _avail * sizeof(Elem),
 623             _size * sizeof(Elem), _autofree) { }
 624
 625     /**
 626      * Creates a new empty buffer backed by a new array.
 627      *
 628      * "_size" is the size of the array
 629      */
 630     explicit WvInPlaceBufBase(size_t _size) :
 631         WvBufBase<T>(& mystore),
 632         mystore(sizeof(Elem), _size * sizeof(Elem)) { }
 633
 634     /** Creates a new empty buffer with no backing array. */
 635     WvInPlaceBufBase() :
 636         WvBufBase<T>(& mystore),
 637         mystore(sizeof(Elem), NULL, 0, 0, false) { }
 638
 639     /**
 640      * Destroys the buffer.
 641      *
 642      * Frees the underlying array if autofree().
 643      *
 644      */
 645     virtual ~WvInPlaceBufBase() { }
 646
 647     /**
 648      * Returns the underlying array pointer.
 649      *
 650      * Returns: the element pointer
 651      */
 652     T *ptr() const
 653     {
 654         return static_cast<T*>(mystore.ptr());
 655     }
 656
 657     /**
 658      * Returns the total size of the buffer.
 659      *
 660      * Returns: the number of elements
 661      */
 662     size_t size() const
 663     {
 664         return mystore.size() / sizeof(Elem);
 665     }
 666
 667     /**
 668      * Returns the autofree flag.
 669      *
 670      * Returns: the autofree flag
 671      */
 672     bool get_autofree() const
 673     {
 674         return mystore.get_autofree();
 675     }
 676
 677     /**
 678      * Sets or clears the autofree flag.
 679      *
 680      * "_autofree" is if true, the array will be freed when discarded
 681      */
 682     void set_autofree(bool _autofree)
 683     {
 684         mystore.set_autofree(_autofree);
 685     }
 686
 687     /**
 688      * Resets the underlying buffer pointer and properties.
 689      *
 690      * If the old and new buffer pointers differ and the old buffer
 691      * was specified as autofree, the old buffer is destroyed.
 692      *
 693      * "_data" is the array of data to wrap
 694      * "_avail" is the amount of data available for reading
 695      * "_size" is the size of the array
 696      * "_autofree" is if true, the array will be freed when discarded
 697      */
 698     void reset(T *_data, size_t _avail, size_t _size,
 699         bool _autofree = false)
 700     {
 701         mystore.reset(_data, _avail * sizeof(Elem),
 702             _size * sizeof(Elem), _autofree);
 703     }
 704
 705     /**
 706      * Sets the amount of available data using the current buffer
 707      * and resets the read index to the beginning of the buffer.
 708      *
 709      * "_avail" is the amount of data available for reading
 710      */
 711     void setavail(size_t _avail)
 712     {
 713         mystore.setavail(_avail * sizeof(Elem));
 714     }
 715 };
 716
 717
 718
 719 /**
 720  * A buffer that wraps a pre-allocated array and provides
 721  * read-only access to its elements.
 722  *
 723  * "T" is the type of object to store, must be a primitive or a struct
 724  *        without special initialization, copy, or assignment semantics
 725  */
 726 template<class T>
 727 class WvConstInPlaceBufBase : public WvBufBase<T>
 728 {
 729 protected:
 730     typedef T Elem;
 731
 732     WvConstInPlaceBufStore mystore;
 733
 734 public:
 735     /**
 736      * Creates a new buffer backed by the supplied array.
 737      *
 738      * "_data" is the array of data to wrap
 739      * "_avail" is the amount of data available for reading
 740      */
 741     WvConstInPlaceBufBase(const T *_data, size_t _avail) :
 742         WvBufBase<T>(& mystore),
 743         mystore(sizeof(Elem), _data, _avail * sizeof(Elem)) { }
 744
 745     /** Creates a new empty buffer with no backing array. */
 746     WvConstInPlaceBufBase() :
 747         WvBufBase<T>(& mystore),
 748         mystore(sizeof(Elem), NULL, 0) { }
 749
 750     /**
 751      * Destroys the buffer.
 752      *
 753      * Never frees the underlying array.
 754      *
 755      */
 756     virtual ~WvConstInPlaceBufBase() { }
 757
 758     /**
 759      * Returns the underlying array pointer.
 760      *
 761      * Returns: the element pointer
 762      */
 763     const T *ptr() const
 764     {
 765         return static_cast<const T*>(mystore.ptr());
 766     }
 767
 768     /**
 769      * Resets the underlying buffer pointer and properties.
 770      *
 771      * Never frees the old buffer.
 772      *
 773      *
 774      * "_data" is the array of data to wrap
 775      * "_avail" is the amount of data available for reading
 776      */
 777     void reset(const T *_data, size_t _avail)
 778     {
 779         mystore.reset(_data, _avail * sizeof(Elem));
 780     }
 781
 782     /**
 783      * Sets the amount of available data using the current buffer
 784      * and resets the read index to the beginning of the buffer.
 785      *
 786      * "_avail" is the amount of data available for reading
 787      */
 788     void setavail(size_t _avail)
 789     {
 790         mystore.setavail(_avail * sizeof(Elem));
 791     }
 792 };
 793
 794
 795
 796 /**
 797  * A buffer that wraps a pre-allocated array and provides
 798  * read-write access to its elements using a circular buffering
 799  * scheme rather than a purely linear one, as used by
 800  * WvInPlaceBuf.
 801  *
 802  * When there is insufficient contigous free/used space to
 803  * satisfy a read or write request, the data is automatically
 804  * reordered in-place to coalesce the free/used spaces into
 805  * sufficiently large chunks.  The process may also be manually
 806  * triggered to explicitly renormalize the array and shift its
 807  * contents to the front.
 808  *
 809  * "T" is the type of object to store, must be a primitive or a struct
 810  *        without special initialization, copy, or assignment semantics
 811  */
 812 template<class T>
 813 class WvCircularBufBase : public WvBufBase<T>
 814 {
 815 protected:
 816     typedef T Elem;
 817
 818     WvCircularBufStore mystore;
 819
 820 public:
 821     /**
 822      * Creates a new circular buffer backed by the supplied array.
 823      *
 824      * "_data" is the array of data to wrap
 825      * "_avail" is the amount of data available for reading
 826      *               at the beginning of the buffer
 827      * "_size" is the size of the array
 828      * "_autofree" is if true, the array will be freed when discarded
 829      */
 830     WvCircularBufBase(T *_data, size_t _avail, size_t _size,
 831         bool _autofree = false) :
 832         WvBufBase<T>(& mystore),
 833         mystore(sizeof(Elem), _data, _avail * sizeof(Elem),
 834             _size * sizeof(Elem), _autofree) { }
 835
 836     /**
 837      * Creates a new empty circular buffer backed by a new array.
 838      *
 839      * "_size" is the size of the array
 840      */
 841     explicit WvCircularBufBase(size_t _size) :
 842         WvBufBase<T>(& mystore),
 843         mystore(sizeof(Elem), _size * sizeof(Elem)) { }
 844
 845     /** Creates a new empty buffer with no backing array. */
 846     WvCircularBufBase() :
 847         WvBufBase<T>(& mystore),
 848         mystore(sizeof(Elem), NULL, 0, 0, false) { }
 849
 850     /**
 851      * Destroys the buffer.
 852      *
 853      * Frees the underlying array if autofree().
 854      *
 855      */
 856     virtual ~WvCircularBufBase() { }
 857
 858     /**
 859      * Returns the underlying array pointer.
 860      *
 861      * Returns: the element pointer
 862      */
 863     T *ptr() const
 864     {
 865         return static_cast<T*>(mystore.ptr());
 866     }
 867
 868     /**
 869      * Returns the total size of the buffer.
 870      *
 871      * Returns: the number of elements
 872      */
 873     size_t size() const
 874     {
 875         return mystore.size() / sizeof(Elem);
 876     }
 877
 878     /**
 879      * Returns the autofree flag.
 880      *
 881      * Returns: the autofree flag
 882      */
 883     bool get_autofree() const
 884     {
 885         return mystore.get_autofree();
 886     }
 887
 888     /**
 889      * Sets or clears the autofree flag.
 890      *
 891      * "_autofree" is if true, the array will be freed when discarded
 892      */
 893     void set_autofree(bool _autofree)
 894     {
 895         mystore.set_autofree(_autofree);
 896     }
 897
 898     /**
 899      * Resets the underlying buffer pointer and properties.
 900      *
 901      * If the old and new buffer pointers differ and the old buffer
 902      * was specified as autofree, the old buffer is destroyed.
 903      *
 904      * "_data" is the array of data to wrap
 905      * "_avail" is the amount of data available for reading
 906      *               at the beginning of the buffer
 907      * "_size" is the size of the array
 908      * "_autofree" is if true, the array will be freed when discarded
 909      */
 910     void reset(T *_data, size_t _avail, size_t _size,
 911         bool _autofree = false)
 912     {
 913         mystore.reset(_data, _avail * sizeof(Elem),
 914             _size * sizeof(Elem), _autofree);
 915     }
 916
 917     /**
 918      * Sets the amount of available data using the current buffer
 919      * and resets the read index to the beginning of the buffer.
 920      *
 921      * "_avail" is the amount of data available for reading
 922      *               at the beginning of the buffer
 923      */
 924     void setavail(size_t _avail)
 925     {
 926         mystore.setavail(_avail * sizeof(Elem));
 927     }
 928
 929     /**
 930      * Normalizes the arrangement of the data such that the
 931      * contents of the buffer are stored at the beginning of
 932      * the array starting with the next element that would be
 933      * returned by get(size_t).
 934      *
 935      * After invocation, ungettable() may equal 0.
 936      *
 937      */
 938     void normalize()
 939     {
 940         mystore.normalize();
 941     }
 942 };
 943
 944
 945
 946 /**
 947  * A buffer that dynamically grows and shrinks based on demand.
 948  *
 949  * "T" is the type of object to store, must be a primitive or a struct
 950  *        without special initialization, copy, or assignment semantics
 951  */
 952 template<class T>
 953 class WvDynBufBase : public WvBufBase<T>
 954 {
 955 protected:
 956     typedef T Elem;
 957
 958     WvDynBufStore mystore;
 959
 960 public:
 961     /**
 962      * Creates a new buffer.
 963      *
 964      * Provides some parameters for tuning response to buffer
 965      * growth.
 966      *
 967      * "_minalloc" is the minimum number of elements to allocate
 968      *      at once when creating a new internal buffer segment
 969      * "_maxalloc" is the maximum number of elements to allocate
 970      *      at once when creating a new internal buffer segment
 971      *      before before reverting to a linear growth pattern
 972      */
 973     explicit WvDynBufBase(size_t _minalloc = 1024,
 974         size_t _maxalloc = 1048576) :
 975         WvBufBase<T>(& mystore),
 976         mystore(sizeof(Elem), _minalloc * sizeof(Elem),
 977             _maxalloc * sizeof(Elem)) { }
 978 };
 979
 980
 981
 982 /**
 983  * A buffer that is always empty.
 984  *
 985  * "T" is the type of object to store, must be a primitive or a struct
 986  *        without special initialization, copy, or assignment semantics
 987  */
 988 template<class T>
 989 class WvNullBufBase : public WvBufBase<T>
 990 {
 991 protected:
 992     typedef T Elem;
 993
 994     WvNullBufStore mystore;
 995
 996 public:
 997     /** Creates a new buffer. */
 998     WvNullBufBase() :
 999         WvBufBase<T>(& mystore),
1000         mystore(sizeof(Elem)) { }
1001 };
1002
1003
1004
1005 /**
1006  * A buffer that acts like a cursor over a portion of another buffer.
1007  * The underlying buffer's get() position is not affected by
1008  * reading from this buffer.
1009  *
1010  * "T" is the type of object to store, must be a primitive or a struct
1011  *        without special initialization, copy, or assignment semantics
1012  */
1013 template<class T>
1014 class WvBufCursorBase : public WvBufBase<T>
1015 {
1016 protected:
1017     typedef T Elem;
1018
1019     WvBufCursorStore mystore;
1020
1021 public:
1022     /**
1023      * Creates a new buffer.
1024      *
1025      * Does not take ownership of the supplied buffer.
1026      *
1027      *
1028      * "_buf" is a pointer to the buffer to be wrapped
1029      * "_start" is the buffer offset of the window start position
1030      * "_length" is the length of the window
1031      */
1032     WvBufCursorBase(WvBufBase<T> &_buf, int _start,
1033         size_t _length) :
1034         WvBufBase<T>(& mystore),
1035         mystore(sizeof(Elem), _buf.getstore(),
1036             _start * sizeof(Elem), _length * sizeof(Elem)) { }
1037 };
1038
1039
1040 /**
1041  * A buffer that provides a read-write view over another buffer
1042  * with a different datatype.  Reading and writing through this
1043  * buffer implicitly performs the equivalent of reinterpret_cast
1044  * on each element.
1045  *
1046  * Most useful for manipulating data backed by a raw memory buffer.
1047  *
1048  * "T" is the type of object to store, must be a primitive or a struct
1049  *        without special initialization, copy, or assignment semantics
1050  */
1051 template<class T>
1052 class WvBufViewBase : public WvBufBase<T>
1053 {
1054 public:
1055     /**
1056      * Creates a new buffer.
1057      *
1058      * Does not take ownership of the supplied buffer.
1059      *
1060      *
1061      * "_buf" is a pointer to the buffer to be wrapped
1062      */
1063     template<typename S>
1064     WvBufViewBase(WvBufBase<S> &_buf) :
1065         WvBufBase<T>(_buf.getstore()) { }
1066 };
1067
1068 #endif // __WVBUFFERBASE_H