ceph/src/boost/libs/ptr_container/doc/guidelines.rst

   1 ++++++++++++++++++++++++++++++++++
   2  |Boost| Pointer Container Library
   3 ++++++++++++++++++++++++++++++++++
   4
   5 .. |Boost| image:: boost.png
   6
   7 ================
   8 Usage Guidelines
   9 ================
  10
  11 .. contents:: :local:
  12
  13 Choosing the right container
  14 ----------------------------
  15
  16 The recommended usage pattern of the container classes is the same as
  17 for normal standard containers.
  18
  19 ``ptr_vector``, ``ptr_list`` and ``ptr_deque`` offer the programmer different
  20 complexity tradeoffs and should be used accordingly.  ``ptr_vector`` is the
  21 type of sequence that should be used by default.  ``ptr_list`` should be used
  22 when there are frequent insertions and deletions from the middle of the
  23 sequence and if the container is fairly large (eg.  more than 100
  24 elements).  ``ptr_deque`` is the data structure of choice when most insertions
  25 and deletions take place at the beginning or at the end of the sequence.
  26 The special container ``ptr_array`` may be used when the size of the container is invariant
  27 and known at compile time.
  28
  29 An associative container supports unique keys if it may contain at most
  30 one element for each key. Otherwise, it supports equivalent keys.
  31 ``ptr_set`` and ``ptr_map`` support unique keys.
  32 ``ptr_multiset`` and ``ptr_multimap``
  33 support equivalent keys.
  34
  35 Recommended practice for Object-Oriented Programming
  36 ----------------------------------------------------
  37
  38 Idiomatic Object-Oriented Programming in C++ looks a bit different from
  39 the way it is done in other languages. This is partly because C++
  40 has both value and reference semantics, and partly because C++ is more flexible
  41 than other languages. Below is a list of recommendations that you are
  42 encouraged to follow:
  43
  44 1. Make base classes abstract and without data
  45 ++++++++++++++++++++++++++++++++++++++++++++++
  46
  47 This has the following advantages:
  48
  49         a. It reduces *coupling* because you do not have to maintain or update state
  50
  51         ..
  52
  53         b. It helps you to avoid *slicing*
  54
  55         ..
  56
  57         c. It ensures you *override* the right function
  58
  59 You might also want to read the following articles:
  60
  61 - Kevlin Henney's `Six of the best`__
  62
  63 .. __: http://www.two-sdg.demon.co.uk/curbralan/papers/SixOfTheBest.pdf
  64
  65 - Jack Reeves' `Multiple Inheritance Considered Useful`__
  66
  67 .. __: http://www.ddj.com/documents/s=10011/q=1/cuj0602reeves/0602reeves.html
  68
  69
  70 2. Make virtual functions private and provide a non-virtual public forwarding function
  71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  72
  73 In code::
  74
  75         class Polymorphic
  76         {
  77         private:
  78             virtual int do_foo() = 0;
  79
  80         public:
  81             int foo()
  82             {
  83                 return do_foo();
  84             }
  85             ...
  86         };
  87
  88 This has the following advantages:
  89
  90         a. It makes sure all calls to the virtual function always goes through one place in your code
  91
  92         ..
  93
  94         b. It enables you to check preconditions and postconditions inside the forwarding function
  95
  96 You might also want to read Herb Sutter's article `Virtuality`__.
  97
  98 .. __: http://www.gotw.ca/publications/mill18.htm
  99
 100 3. Derive your base class from ``boost::noncopyable``
 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 102
 103 Having an abstact base class prevents slicing when the base class is involved, but
 104 it does not prevent it for classes further down the hierarchy. This is where
 105 `boost::noncopyable`__ is handy to use::
 106
 107         class Polymorphic : boost::noncopyable
 108         {
 109           ...
 110         };
 111
 112 .. __ : http://www.boost.org/libs/utility/utility.htm#Class_noncopyable
 113
 114
 115 4. Avoid null-pointers in containers (if possible)
 116 ++++++++++++++++++++++++++++++++++++++++++++++++++
 117
 118 By default the pointer containers do not allow you to store null-pointer in them.
 119 As you might know, this behavior can be changed explicitly with the use
 120 of `boost::nullable`__.
 121
 122 The primary reason to avoid null-pointers
 123 is that you have to check for null-pointers every time the container is
 124 used. This extra checking is easy to forget, and it is somewhat contradictory to
 125 the spirit of OO where you replace special cases with dynamic dispatch.
 126
 127 .. __: reference.html#class-nullable
 128
 129 Often, however, you need to place some special object in the container because you
 130 do not have enough information to construct a full object. In that case
 131 you might be able to use the Null Object pattern which simply dictates that
 132 you implement virtual functions from the abstract base-class
 133 as empty functions or with dummy return values. This means that
 134 your OO-code still does not need to worry about null-pointers.
 135
 136 You might want to read
 137
 138 - Kevlin Henney's `Null Object - Something for Nothing`__
 139
 140 .. __: http://www.two-sdg.demon.co.uk/curbralan/papers/europlop/NullObject.pdf
 141
 142 Finally you might end up in a situation where not even the Null Object can help
 143 you. That is when you truly need ``container< nullable<T> >``.
 144
 145 .. raw:: html
 146
 147         <hr>
 148
 149 **Navigate:**
 150
 151 - `home <ptr_container.html>`_
 152 - `reference <reference.html>`_
 153
 154 .. raw:: html
 155
 156         <hr>
 157
 158 :Copyright:     Thorsten Ottosen 2004-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
 159
 160 __ http://www.boost.org/LICENSE_1_0.txt
 161
 162