[svn-commits] mmichelson: branch group/CCSS r247920 - /team/group/CCSS/main/ccss.c

Fri Feb 19 12:11:05 CST 2010

Author: mmichelson
Date: Fri Feb 19 12:11:02 2010
New Revision: 247920

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=247920
Log:
Add some doxygen and do a bit of rearranging.


Modified:
    team/group/CCSS/main/ccss.c

Modified: team/group/CCSS/main/ccss.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/main/ccss.c?view=diff&rev=247920&r1=247919&r2=247920
==============================================================================

--- team/group/CCSS/main/ccss.c (original)
+++ team/group/CCSS/main/ccss.c Fri Feb 19 12:11:02 2010
@@ -66,18 +66,40 @@
  * they are used in many places throughout the file, defining
  * them here at the top is easiest.
  */
+
+/*!
+ * The sched_thread ID used for all generic CC timeouts
+ */
 static struct ast_sched_thread *cc_sched_thread;
-static const int CC_CORE_INSTANCES_BUCKETS = 17;
+/*!
+ * Counter used to create core IDs for CC calls. Each new
+ * core ID is created by atomically adding 1 to the core_id_counter
+ */
 static int core_id_counter;
+/*!
+ * Taskprocessor from which all CC agent and monitor callbacks
+ * are called.
+ */
 static struct ast_taskprocessor *cc_core_taskprocessor;
+/*!
+ * Name printed on all CC log messages.
+ */
+static const char *CC_LOGGER_LEVEL_NAME = "CC";
+/*!
+ * Logger level registered by the CC core.
+ */
+static int cc_logger_level;
+/*!
+ * Parsed configuration value for cc_max_requests
+ */
+static unsigned int global_cc_max_requests;
+/*!
+ * The current number of CC requests in the system
+ */
+static int cc_request_count;
 
 #define cc_ref(obj, debug) ({ao2_t_ref((obj), +1, (debug)); (obj);})
 #define cc_unref(obj, debug) ({ao2_t_ref((obj), -1, (debug)); NULL;})
-
-/* Parsed configuration value for cc_max_requests */
-static unsigned int global_cc_max_requests;
-/* The actual number of CC requests in the system */
-static int cc_request_count;
 
 /*!
  * \since 1.8
@@ -112,28 +134,10 @@
 	 */
 	CC_COMPLETE,
 	/*! Entered any time that something goes wrong during the process, thus
-	 * resulting in the failure of the attempted CCSS transaction
+	 * resulting in the failure of the attempted CCSS transaction. Note also
+	 * that cancellations of CC are treated as failures.
 	 */
 	CC_FAILED,
-};
-
-/*!
- * \since 1.8
- * \internal
- * \brief A structure for holding the configuration parameters
- * relating to CCSS
- */
-struct ast_cc_config_params {
-	enum ast_cc_agent_policies cc_agent_policy;
-	enum ast_cc_monitor_policies cc_monitor_policy;
-	unsigned int cc_offer_timer;
-	unsigned int ccnr_available_timer;
-	unsigned int ccbs_available_timer;
-	unsigned int cc_recall_timer;
-	unsigned int cc_max_agents;
-	unsigned int cc_max_monitors;
-	char cc_callback_macro[AST_MAX_EXTENSION];
-	char cc_agent_dialstring[AST_MAX_EXTENSION];
 };
 
 /*!
@@ -233,11 +237,42 @@
 /*!
  * \brief The "tree" of interfaces that is dialed.
  *
- * It is reference counted since several threads may need
+ * \details
+ * Though this is a linked list, it is logically treated
+ * as a tree of monitors. Each monitor has an id and a parent_id
+ * associated with it. The id is a unique ID for that monitor, and
+ * the parent_id is the unique ID of the monitor's parent in the
+ * tree. The tree is structured such that all of a parent's children
+ * will appear after the parent in the tree. However, it cannot be
+ * guaranteed exactly where after the parent the children are.
+ *
+ * The tree is reference counted since several threads may need
  * to use it, and it may last beyond the lifetime of a single
  * thread.
  */
 AST_LIST_HEAD(cc_monitor_tree, ast_cc_monitor);
+
+static const int CC_CORE_INSTANCES_BUCKETS = 17;
+static struct ao2_container *cc_core_instances;
+
+struct cc_core_instance {
+	/*!
+	 * Unique identifier for this instance of the CC core.
+	 */
+	int core_id;
+	/*!
+	 * The current state for this instance of the CC core.
+	 */
+	enum cc_state current_state;
+	/*!
+	 * The CC agent in use for this call
+	 */
+	struct ast_cc_agent *agent;
+	/*!
+	 * Reference to the monitor tree formed during the initial call
+	 */
+	struct cc_monitor_tree *monitors;
+};
 
 /*!
  * \internal
@@ -272,9 +307,6 @@
  */
 static struct cc_core_instance *cc_core_init_instance(struct ast_channel *caller_chan,
 		struct cc_monitor_tree *called_tree, const int core_id, struct cc_control_payload *cc_data);
-
-static const char *CC_LOGGER_LEVEL_NAME = "CC";
-static int cc_logger_level;
 
 static struct {
 	enum ast_cc_service_type service;
@@ -311,30 +343,6 @@
 	return cc_service_to_string_map[service].service_string;
 }
 
-static struct ao2_container *cc_core_instances;
-
-struct cc_core_instance {
-	/*!
-	 * Unique identifier for this instance of the CC core.
-	 */
-	int core_id;
-	/*!
-	 * The current state for this instance of the CC core.
-	 */
-	enum cc_state current_state;
-	/*!
-	 * The CC agent in use for this call
-	 */
-	struct ast_cc_agent *agent;
-	/*!
-	 * Reference to the root of the monitor tree
-	 *
-	 * This pointer's nullity is a way of testing
-	 * whether CC has been requested yet.
-	 */
-	struct cc_monitor_tree *monitors;
-};
-
 static int cc_core_instance_hash_fn(const void *obj, const int flags)
 {
 	const struct cc_core_instance *core_instance = obj;
@@ -471,6 +479,25 @@
 static const unsigned int CC_MAX_AGENTS_DEFAULT = 5u;
 static const unsigned int CC_MAX_MONITORS_DEFAULT = 5u;
 static const unsigned int GLOBAL_CC_MAX_REQUESTS_DEFAULT = 20u;
+
+/*!
+ * \since 1.8
+ * \internal
+ * \brief A structure for holding the configuration parameters
+ * relating to CCSS
+ */
+struct ast_cc_config_params {
+	enum ast_cc_agent_policies cc_agent_policy;
+	enum ast_cc_monitor_policies cc_monitor_policy;
+	unsigned int cc_offer_timer;
+	unsigned int ccnr_available_timer;
+	unsigned int ccbs_available_timer;
+	unsigned int cc_recall_timer;
+	unsigned int cc_max_agents;
+	unsigned int cc_max_monitors;
+	char cc_callback_macro[AST_MAX_EXTENSION];
+	char cc_agent_dialstring[AST_MAX_EXTENSION];
+};
 
 struct ast_cc_config_params *__ast_cc_config_params_init(const char *file, int line, const char *function)
 {


