/thirdparty/breakpad/processor/contained_range_map.h

http://github.com/tomahawk-player/tomahawk · C++ Header · 150 lines · 31 code · 22 blank · 97 comment · 0 complexity · 9fa2977639554b4587440c0a28d65b8e MD5 · raw file

  1. // Copyright (c) 2006, Google Inc.
  2. // All rights reserved.
  3. //
  4. // Redistribution and use in source and binary forms, with or without
  5. // modification, are permitted provided that the following conditions are
  6. // met:
  7. //
  8. // * Redistributions of source code must retain the above copyright
  9. // notice, this list of conditions and the following disclaimer.
  10. // * Redistributions in binary form must reproduce the above
  11. // copyright notice, this list of conditions and the following disclaimer
  12. // in the documentation and/or other materials provided with the
  13. // distribution.
  14. // * Neither the name of Google Inc. nor the names of its
  15. // contributors may be used to endorse or promote products derived from
  16. // this software without specific prior written permission.
  17. //
  18. // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22. // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23. // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24. // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25. // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26. // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27. // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28. // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. // contained_range_map.h: Hierarchically-organized range maps.
  30. //
  31. // A contained range map is similar to a standard range map, except it allows
  32. // objects to be organized hierarchically. A contained range map allows
  33. // objects to contain other objects. It is not sensitive to the order that
  34. // objects are added to the map: larger, more general, containing objects
  35. // may be added either before or after smaller, more specific, contained
  36. // ones.
  37. //
  38. // Contained range maps guarantee that each object may only contain smaller
  39. // objects than itself, and that a parent object may only contain child
  40. // objects located entirely within the parent's address space. Attempts
  41. // to introduce objects (via StoreRange) that violate these rules will fail.
  42. // Retrieval (via RetrieveRange) always returns the most specific (smallest)
  43. // object that contains the address being queried. Note that while it is
  44. // not possible to insert two objects into a map that have exactly the same
  45. // geometry (base address and size), it is possible to completely mask a
  46. // larger object by inserting smaller objects that entirely fill the larger
  47. // object's address space.
  48. //
  49. // Internally, contained range maps are implemented as a tree. Each tree
  50. // node except for the root node describes an object in the map. Each node
  51. // maintains its list of children in a map similar to a standard range map,
  52. // keyed by the highest address that each child occupies. Each node's
  53. // children occupy address ranges entirely within the node. The root node
  54. // is the only node directly accessible to the user, and represents the
  55. // entire address space.
  56. //
  57. // Author: Mark Mentovai
  58. #ifndef PROCESSOR_CONTAINED_RANGE_MAP_H__
  59. #define PROCESSOR_CONTAINED_RANGE_MAP_H__
  60. #include <map>
  61. namespace google_breakpad {
  62. // Forward declarations (for later friend declarations of specialized template).
  63. template<class, class> class ContainedRangeMapSerializer;
  64. template<typename AddressType, typename EntryType>
  65. class ContainedRangeMap {
  66. public:
  67. // The default constructor creates a ContainedRangeMap with no geometry
  68. // and no entry, and as such is only suitable for the root node of a
  69. // ContainedRangeMap tree.
  70. ContainedRangeMap() : base_(), entry_(), map_(NULL) {}
  71. ~ContainedRangeMap();
  72. // Inserts a range into the map. If the new range is encompassed by
  73. // an existing child range, the new range is passed into the child range's
  74. // StoreRange method. If the new range encompasses any existing child
  75. // ranges, those child ranges are moved to the new range, becoming
  76. // grandchildren of this ContainedRangeMap. Returns false for a
  77. // parameter error, or if the ContainedRangeMap hierarchy guarantees
  78. // would be violated.
  79. bool StoreRange(const AddressType &base,
  80. const AddressType &size,
  81. const EntryType &entry);
  82. // Retrieves the most specific (smallest) descendant range encompassing
  83. // the specified address. This method will only return entries held by
  84. // child ranges, and not the entry contained by |this|. This is necessary
  85. // to support a sparsely-populated root range. If no descendant range
  86. // encompasses the address, returns false.
  87. bool RetrieveRange(const AddressType &address, EntryType *entry) const;
  88. // Removes all children. Note that Clear only removes descendants,
  89. // leaving the node on which it is called intact. Because the only
  90. // meaningful things contained by a root node are descendants, this
  91. // is sufficient to restore an entire ContainedRangeMap to its initial
  92. // empty state when called on the root node.
  93. void Clear();
  94. private:
  95. friend class ContainedRangeMapSerializer<AddressType, EntryType>;
  96. friend class ModuleComparer;
  97. // AddressToRangeMap stores pointers. This makes reparenting simpler in
  98. // StoreRange, because it doesn't need to copy entire objects.
  99. typedef std::map<AddressType, ContainedRangeMap *> AddressToRangeMap;
  100. typedef typename AddressToRangeMap::const_iterator MapConstIterator;
  101. typedef typename AddressToRangeMap::iterator MapIterator;
  102. typedef typename AddressToRangeMap::value_type MapValue;
  103. // Creates a new ContainedRangeMap with the specified base address, entry,
  104. // and initial child map, which may be NULL. This is only used internally
  105. // by ContainedRangeMap when it creates a new child.
  106. ContainedRangeMap(const AddressType &base, const EntryType &entry,
  107. AddressToRangeMap *map)
  108. : base_(base), entry_(entry), map_(map) {}
  109. // The base address of this range. The high address does not need to
  110. // be stored, because it is used as the key to an object in its parent's
  111. // map, and all ContainedRangeMaps except for the root range are contained
  112. // within maps. The root range does not actually contain an entry, so its
  113. // base_ field is meaningless, and the fact that it has no parent and thus
  114. // no key is unimportant. For this reason, the base_ field should only be
  115. // is accessed on child ContainedRangeMap objects, and never on |this|.
  116. const AddressType base_;
  117. // The entry corresponding to this range. The root range does not
  118. // actually contain an entry, so its entry_ field is meaningless. For
  119. // this reason, the entry_ field should only be accessed on child
  120. // ContainedRangeMap objects, and never on |this|.
  121. const EntryType entry_;
  122. // The map containing child ranges, keyed by each child range's high
  123. // address. This is a pointer to avoid allocating map structures for
  124. // leaf nodes, where they are not needed.
  125. AddressToRangeMap *map_;
  126. };
  127. } // namespace google_breakpad
  128. #endif // PROCESSOR_CONTAINED_RANGE_MAP_H__