[03/48] git commit: TS-2177: Improve code quality of FeatureAPIHooks.

[zw...@apache.org]

TS-2177: Improve code quality of FeatureAPIHooks.


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/0ec6fc7e
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/0ec6fc7e
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/0ec6fc7e

Branch: refs/heads/5.0.x
Commit: 0ec6fc7e12f79f84fa284015493dfc92f1ca5413
Parents: c05a097
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Wed Sep 4 12:00:47 2013 -0500
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Wed Sep 4 12:00:47 2013 -0500

----------------------------------------------------------------------
 proxy/InkAPIInternal.h | 78 +++++++++++++++++++++++++++++++++------------
 1 file changed, 58 insertions(+), 20 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/0ec6fc7e/proxy/InkAPIInternal.h
----------------------------------------------------------------------
diff --git a/proxy/InkAPIInternal.h b/proxy/InkAPIInternal.h
index fe10601..971e196 100644
--- a/proxy/InkAPIInternal.h
+++ b/proxy/InkAPIInternal.h
@@ -124,6 +124,7 @@ struct HttpAltInfo
   float m_qvalue;
 };
 
+/// A single API hook that can be invoked.
 class APIHook
 {
 public:
@@ -133,6 +134,7 @@ public:
   LINK(APIHook, m_link);
 };
 
+/// A collection of API hooks.
 class APIHooks
 {
 public:
@@ -140,87 +142,123 @@ public:
   void append(INKContInternal * cont);
   APIHook *get();
   void clear();
+  bool is_empty() const;
 
 private:
   Que(APIHook, m_link) m_hooks;
 };
 
+inline bool
+APIHooks::is_empty() const
+{
+  return NULL == m_hooks.head;
+}
+
 /** Container for API hooks for a specific feature.
+
+    This is an array of hook lists, each identified by a numeric identifier (id). Each array element is a list of all
+    hooks for that ID. Adding a hook means adding to the list in the corresponding array element. There is no provision
+    for removing a hook.
+
+    @note The minimum value for a hook ID is zero. Therefore the template parameter @a N_ID should be one more than the
+    maximum hook ID so the valid ids are 0..(N-1) in the standard C array style.
  */
 template <
   typename ID, ///< Type of hook ID
-  ID MAX_ID ///< Maximum value for ID
+  ID N ///< Number of hooks
 >
 class FeatureAPIHooks
 {
 public:
-  FeatureAPIHooks();
-  ~FeatureAPIHooks();
+  FeatureAPIHooks(); ///< Constructor (empty container).
+  ~FeatureAPIHooks(); ///< Destructor.
 
+  /// Remove all hooks.
   void clear();
+  /// Add the hook @a cont to the front of the hooks for @a id.
   void prepend(ID id, INKContInternal * cont);
+  /// Add the hook @a cont to the end of the hooks for @a id.
   void append(ID id, INKContInternal * cont);
+  /// Get the list of hooks for @a id.
   APIHook *get(ID id);
+  /// @return @c true if @a id is a valid id, @c false otherwise.
+  static bool is_valid(ID id);
 
+  /// Fast check for any hooks in this container.
+  ///
+  /// @return @c true if any list has at least one hook, @c false if
+  /// all lists have no hooks.
   bool has_hooks() const;
 
+  /// Check for existence of hooks of a specific @a id.
+  /// @return @c true if any hooks of type @a id are present.
+  bool has_hooks_for(ID id) const;
+
 private:
-  bool hooks_p; ///< Enable fast check for any hooks.
-  APIHooks m_hooks[MAX_ID];
+  bool hooks_p; ///< Flag for (not) empty container.
+  /// The array of hooks lists.
+  APIHooks m_hooks[N];
 };
 
-template < typename ID, ID MAX_ID >
-FeatureAPIHooks<ID,MAX_ID>::FeatureAPIHooks():
+template < typename ID, ID N >
+FeatureAPIHooks<ID,N>::FeatureAPIHooks():
 hooks_p(false)
 {
 }
 
-template < typename ID, ID MAX_ID >
-FeatureAPIHooks<ID,MAX_ID>::~FeatureAPIHooks()
+template < typename ID, ID N >
+FeatureAPIHooks<ID,N>::~FeatureAPIHooks()
 {
   this->clear();
 }
 
-template < typename ID, ID MAX_ID >
+template < typename ID, ID N >
 void
-FeatureAPIHooks<ID,MAX_ID>::clear()
+FeatureAPIHooks<ID,N>::clear()
 {
-  for (int i = 0; i < MAX_ID; ++i) {
+  for (int i = 0; i < N; ++i) {
     m_hooks[i].clear();
   }
   hooks_p = false;
 }
 
-template < typename ID, ID MAX_ID >
+template < typename ID, ID N >
 void
-FeatureAPIHooks<ID,MAX_ID>::prepend(ID id, INKContInternal *cont)
+FeatureAPIHooks<ID,N>::prepend(ID id, INKContInternal *cont)
 {
   hooks_p = true;
   m_hooks[id].prepend(cont);
 }
 
-template < typename ID, ID MAX_ID >
+template < typename ID, ID N >
 void
-FeatureAPIHooks<ID,MAX_ID>::append(ID id, INKContInternal *cont)
+FeatureAPIHooks<ID,N>::append(ID id, INKContInternal *cont)
 {
   hooks_p = true;
   m_hooks[id].append(cont);
 }
 
-template < typename ID, ID MAX_ID >
+template < typename ID, ID N >
 APIHook *
-FeatureAPIHooks<ID,MAX_ID>::get(ID id)
+FeatureAPIHooks<ID,N>::get(ID id)
 {
   return m_hooks[id].get();
 }
 
-template < typename ID, ID MAX_ID >
+template < typename ID, ID N >
 bool
-FeatureAPIHooks<ID,MAX_ID>::has_hooks() const
+FeatureAPIHooks<ID,N>::has_hooks() const
 {
   return hooks_p;
 }
 
+template < typename ID, ID N >
+bool
+FeatureAPIHooks<ID,N>::is_valid(ID id)
+{
+  return 0 <= id && id < N;
+}
+
 class HttpAPIHooks : public FeatureAPIHooks<TSHttpHookID, TS_HTTP_LAST_HOOK>
 {
 };