[PATCH] Comments and tweaks for gnc-component-manager

[Chris Shoemaker]

 * gnc-component-manager tweaks
   - Warn if we approach design limitation of component manager
   - pass GUID as const in gnc_gui_get_entity_events, change
        prototype, callers, and docs
   - Clarify comments about receiving events after entity life-cycle


Index: src/app-utils/gnc-component-manager.c
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/app-utils/gnc-component-manager.c,v
retrieving revision 1.13.4.3
diff -u -r1.13.4.3 gnc-component-manager.c
--- src/app-utils/gnc-component-manager.c	7 Jul 2004 04:10:26 -0000	1.13.4.3
+++ src/app-utils/gnc-component-manager.c	10 Feb 2005 02:10:28 -0000
@@ -392,10 +392,17 @@
   /* look for a free handler id */
   component_id = next_component_id;
 
+  /* design warning: if we ever get 2^32-1 components, 
+     this loop is infinite.  Instead of fixing it, we'll just 
+     complain when (if) we get half way there (probably never).
+  */ 
   while (find_component (component_id))
     if (++component_id == NO_COMPONENT)
       component_id++;
 
+  if (component_id < 0) 
+    PERR("Amazing! Half way to running out of component_ids.");
+  
   /* found one, add the handler */
   ci = g_new0 (ComponentInfo, 1);
 
@@ -520,7 +527,7 @@
 }
 
 const EventInfo *
-gnc_gui_get_entity_events (GHashTable *changes, GUID *entity)
+gnc_gui_get_entity_events (GHashTable *changes, const GUID *entity)
 {
   if (!changes || !entity)
     return GNC_EVENT_NONE;
Index: src/app-utils/gnc-component-manager.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/app-utils/gnc-component-manager.h,v
retrieving revision 1.5.4.1
diff -u -r1.5.4.1 gnc-component-manager.h
--- src/app-utils/gnc-component-manager.h	17 Jul 2003 07:39:48 -0000	1.5.4.1
+++ src/app-utils/gnc-component-manager.h	10 Feb 2005 02:10:28 -0000
@@ -46,8 +46,8 @@
  *          GUIDs to EventInfo structs describing which
  *          events have been received. Entities not in
  *          the hash have not generated any events.
- *          Entities which have been destroyed may not
- *          exist.
+ *          Entities which have been destroyed will be in 
+ *          the hash, but may not exist anymore.
  *
  *          Note since refreshes may not occur with every change,
  *          an entity may have all three change values.
@@ -60,6 +60,15 @@
  *                      entities used by the component may have
  *                      already been deleted. 'Refreshing' the
  *                      component may require closing the component.
+ * 
+ * Notes on dealing with destroyed entities: As stated above, entities
+ * in the changes GHashTable may no longer exist.  So how can you
+ * determine if this has happened?  Well, it's a good idea to check
+ * for the GNC_EVENT_DESTROY bit in the EventInfo structure.  Of
+ * course, that means you need the hash key (GUID) for the destroyed
+ * entity.  How are you going to get the GUID from the entity if the
+ * entity has already been destroyed?  You're not.  So, you have to
+ * save a COPY of the key (GUID) away beforehand.
  *
  * user_data: user_data supplied when component was registered.
  */
@@ -222,7 +231,7 @@
  *          if it is not found.
  */
 const EventInfo * gnc_gui_get_entity_events (GHashTable *changes,
-                                             GUID *entity);
+                                             const GUID *entity);
 
 /* gnc_gui_component_clear_watches
  *   Clear all watches for the component.
Index: src/doc/design/component-manager.texinfo
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/design/component-manager.texinfo,v
retrieving revision 1.5
diff -u -r1.5 component-manager.texinfo
--- src/doc/design/component-manager.texinfo	30 Jul 2001 21:45:58 -0000	1.5
+++ src/doc/design/component-manager.texinfo	10 Feb 2005 02:10:33 -0000
@@ -207,7 +207,7 @@
 
 There is a utility function for accessing the @var{changes} hash:
 
- at deftypefun {const EventInfo *} gnc_gui_get_entity_events (GHashTable * @var{changes}, GUID * @var{entity})
+ at deftypefun {const EventInfo *} gnc_gui_get_entity_events (GHashTable * @var{changes}, const GUID * @var{entity})
 Return the event info for the entity specified by @var{entity}. If there
 are no events for that entity, @code{NULL} is returned.
 @end deftypefun
Index: src/gnome-utils/dialog-query-list.c
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/gnome-utils/dialog-query-list.c,v
retrieving revision 1.3.2.2
diff -u -r1.3.2.2 dialog-query-list.c
--- src/gnome-utils/dialog-query-list.c	25 Oct 2003 06:47:41 -0000	1.3.2.2
+++ src/gnome-utils/dialog-query-list.c	10 Feb 2005 02:10:54 -0000
@@ -140,7 +140,7 @@
   {
     for (node = dql->books; node; node = node->next)
     {
-      info = gnc_gui_get_entity_events (changes, (GUID*)(node->data));
+      info = gnc_gui_get_entity_events (changes, (const GUID*)(node->data));
       if (info && (info->event_mask & GNC_EVENT_DESTROY))
       {
 	gnc_close_gui_component (dql->component_id);