Misc API cleanup: make some engine functions private, etc.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@6173 57a11ea4-9604-0410-9ed3-97b8803252fd

src/backend/file/io-example-account.c

@@ -68,10 +68,8 @@ gnc_destroy_example_account(GncExampleAccount *gea)
     }
     if(gea->group != NULL)
     {
-        /* mark the accounts as being freed
-         * to avoid tons of balance recomputations. */
-        xaccGroupMarkDoFree (gea->group);
-        xaccFreeAccountGroup(gea->group);
+        xaccAccountGroupBeginEdit (gea->group);
+        xaccAccountGroupDestroy(gea->group);
         gea->group = NULL;
     }
     if(gea->short_description != NULL)

src/backend/file/io-gncxml-v1.c

@@ -389,7 +389,11 @@ gnc_session_load_from_xml_file(GNCSession *session)
 
       gnc_book_set_group(book, global_parse_status.account_group);
 
-      if(g) xaccFreeAccountGroup(g);
+      if(g) 
+      {
+        xaccAccountGroupBeginEdit(g);
+        xaccAccountGroupDestroy(g);
+      }
     }
 
     if(global_parse_status.pricedb)
@@ -1208,14 +1212,22 @@ ledger_data_fail_handler(gpointer data_for_children,
                          const gchar *tag)
 {
   AccountGroup *ag = (AccountGroup *) data_for_children;
-  if(ag) xaccFreeAccountGroup(ag);
+  if(ag) 
+  {
+    xaccAccountGroupBeginEdit(ag);
+    xaccAccountGroupDestroy(ag);
+  }
 }
 
 static void
 ledger_data_result_cleanup(sixtp_child_result *cr)
 {
   AccountGroup *ag = (AccountGroup *) cr->data;
-  if(ag) xaccFreeAccountGroup(ag);
+  if(ag) 
+  {
+    xaccAccountGroupBeginEdit(ag);
+    xaccAccountGroupDestroy(ag);
+  }
 }
 
 
@@ -1425,7 +1437,11 @@ account_restore_fail_handler(gpointer data_for_children,
                              const gchar *tag)
 {
   Account *acc = (Account *) *result;
-  if(acc) xaccFreeAccount(acc);
+  if(acc)
+  {
+    xaccAccountBeginEdit (acc);
+    xaccAccountDestroy(acc);
+  }
 }
 
 /****************************************************************************/

src/backend/file/io-gncxml-v2.c

@@ -31,6 +31,7 @@
 #include "gnc-pricedb-p.h"
 #include "gnc-session.h"
 #include "Group.h"
+#include "GroupP.h"
 #include "Scrub.h"
 #include "Transaction.h"
 #include "TransLog.h"
@@ -300,6 +301,10 @@ add_template_transaction_local( sixtp_gdv2 *data,
             xaccGetAccountFromName( acctGroup,
                                     xaccAccountGetName( (Account*)n->data ) );
             if ( tmpAcct != NULL ) {
+/* XXX hack alert FIXME .... Should the be 'Remove', or 'Destroy'?
+ * If we just remove, then this seems to be a memory leak to me, since
+ * it is never reparented.  Shouldn't it be a Destroy ???
+ */
                 xaccGroupRemoveAccount( acctGroup, tmpAcct );
             }
 

src/engine/Account.c

@@ -1202,7 +1202,8 @@ xaccAccountOrder (Account **aa, Account **ab) {
 \********************************************************************/
 
 void 
-xaccAccountSetType (Account *acc, int tip) {
+xaccAccountSetType (Account *acc, GNCAccountType tip) 
+{
 
   if (!acc) return;
 

src/engine/Account.h

@@ -228,7 +228,7 @@ void         xaccTransFixSplitDateOrder (Transaction *trans);
  */
 int          xaccAccountOrder (Account **account_1, Account **account_2);
 
-void xaccAccountSetType (Account *account, int);
+void xaccAccountSetType (Account *account, GNCAccountType);
 void xaccAccountSetName (Account *account, const char *name);
 void xaccAccountSetCode (Account *account, const char *code);
 void xaccAccountSetDescription (Account *account, const char *desc);

src/engine/Group.c

@@ -177,7 +177,7 @@ xaccAccountGroupCommitEdit (AccountGroup *grp)
 /********************************************************************\
 \********************************************************************/
 
-void
+static void
 xaccGroupMarkDoFree (AccountGroup *grp)
 {
   GList *node;
@@ -187,13 +187,18 @@ xaccGroupMarkDoFree (AccountGroup *grp)
   for (node = grp->accounts; node; node = node->next)
   {
     Account *account = node->data;
-
     account->do_free = TRUE;
-
     xaccGroupMarkDoFree (account->children); 
   }
 }
 
+void
+xaccAccountGroupDestroy (AccountGroup *grp)
+{
+   xaccGroupMarkDoFree (grp);
+   xaccFreeAccountGroup (grp);
+}
+
 /********************************************************************\
 \********************************************************************/
 
@@ -260,11 +265,9 @@ xaccFreeAccountGroup (AccountGroup *grp)
     while (grp->accounts->next)
     {
       account = grp->accounts->next->data;
-      xaccAccountBeginEdit (account);
       xaccAccountDestroy (account);
     }
     account = grp->accounts->data;
-    xaccAccountBeginEdit (account);
     xaccAccountDestroy (account);
 
     if (!root_grp) return;
@@ -719,6 +722,9 @@ xaccGroupInsertAccount (AccountGroup *grp, Account *acc)
           * will have a different backend than the 'to' book.  This means
           * that we should get the 'from' backend to destroy this account,
           * and the 'to' backend to save it.  Right now, this is broken.
+          *  
+          * A 'correct' implementation similar to this is in Period.c
+          * except its for transactions ...
           */
          PWARN ("reparenting accounts accross books is not correctly supported\n");
 
@@ -1184,12 +1190,12 @@ xaccGroupForEachTransaction (AccountGroup *g,
 /********************************************************************\
 \********************************************************************/
 
-GSList *
+AccountList *
 xaccGroupMapAccounts (AccountGroup *grp,
                       gpointer (*thunk)(Account *a, gpointer data),
                       gpointer data)
 {
-  GSList *result = NULL;
+  GList *result = NULL;
   GList *node;
 
   if (!grp) return(NULL);
@@ -1201,10 +1207,12 @@ xaccGroupMapAccounts (AccountGroup *grp,
     gpointer thunk_result = thunk (account, data);
 
     if (thunk_result)
-      result = g_slist_prepend (result, thunk_result);
+    {
+      result = g_list_append (result, thunk_result);
+    }
   }
 
-  return(g_slist_reverse (result));
+  return (result);
 }
 
 gpointer
@@ -1236,3 +1244,5 @@ xaccGroupForEachAccount (AccountGroup *grp,
 
   return(NULL);
 }
+
+/* ========================= END OF FILE ======================== */

src/engine/Group.h

@@ -34,8 +34,14 @@
 
 
 /** PROTOTYPES ******************************************************/
+/*
+ * The xaccAccountDestroy() routine will destroy and free all 
+ *    the data associated with this account group.  The group
+ *    must have been opened for editing with 
+ *    xaccAccountGroupBeginEdit() first, before the Destroy is called.
+ */
 AccountGroup *xaccMallocAccountGroup (GNCBook *book);
-void          xaccFreeAccountGroup (AccountGroup *account_group);
+void          xaccAccountGroupDestroy (AccountGroup *grp);
 
 GNCBook * xaccGroupGetBook (AccountGroup *group);
 
@@ -76,32 +82,13 @@ void    xaccGroupMergeAccounts (AccountGroup *grp);
  *
  * The xaccGroupMarkNotSaved() subroutine will mark
  *    the given group as not having been saved.
- *
- * The xaccGroupMarkDoFree() subroutine will mark
- *    all accounts in the group as being destroyed.
  */
 
 gboolean xaccGroupNotSaved  (AccountGroup *grp);
 void     xaccGroupMarkSaved (AccountGroup *grp);
 void     xaccGroupMarkNotSaved (AccountGroup *grp);
 
-void     xaccGroupMarkDoFree (AccountGroup *grp);
-
 /*
- * The xaccGroupRemoveAccount() subroutine will remove the indicated
- *    account from its parent account group. It will NOT free the
- *    associated memory or otherwise alter the account: the account
- *    can now be reparented to a new location.
- *    Note, however, that it will mark the old parents as having 
- *    been modified.
- *
- * The xaccAccountRemoveGroup() subroutine will remove the indicated
- *    account group from its parent account. It will NOT free the
- *    associated memory or otherwise alter the account group: the 
- *    account group can now be reparented to a new location.
- *    Note, however, that it will mark the old parents as having 
- *    been modified.
- *
  * The xaccGroupInsertAccount() subroutine will insert the indicated
  *    account into the indicated group.  If it already is the child 
  *    of another group, it will be removed there first.  If the
@@ -115,8 +102,6 @@ void     xaccGroupMarkDoFree (AccountGroup *grp);
  *    the parent is specified as an account.
  */
 
-void    xaccGroupRemoveAccount (AccountGroup *grp, Account *account);
-void    xaccAccountRemoveGroup (Account *acc);
 void    xaccGroupInsertAccount (AccountGroup *grp, Account *acc);
 void    xaccAccountInsertSubAccount (Account *parent, Account *child);
 
@@ -194,10 +179,14 @@ AccountGroup * xaccAccountGetRoot (Account *account);
  */
 Account * xaccGroupGetParentAccount (AccountGroup *group);
 
-/* if the function returns null for a given item, it won't show up in
-   the result list */
+/* The xaccGroupMapAccounts() routine will traverse the account 
+      group, returning a list of accounts.  If teh callback
+      returns null for a given item, it won't show up in
+      the result list.  You should free the returned list when
+      you are done with it.
+*/
 typedef  gpointer (*AccountCallback)(Account *a, gpointer data);
-GSList *xaccGroupMapAccounts(AccountGroup *grp,
+AccountList *xaccGroupMapAccounts(AccountGroup *grp,
                              AccountCallback,
                              gpointer data);
 

src/engine/GroupP.h

@@ -61,4 +61,37 @@ struct account_group_s
 
 void xaccGroupSetBook (AccountGroup *group, GNCBook *book);
 
+/*
+ * The xaccAccountRemoveGroup() subroutine will remove the indicated
+ *    account group from its parent account. It will NOT free the
+ *    associated memory or otherwise alter the account group: the
+ *    account group can now be reparented to a new location.
+ *    Note, however, that it will mark the old parents as having
+ *    been modified.
+ *
+ * The xaccGroupRemoveAccount() subroutine will remove the indicated
+ *    account from its parent account group. It will NOT free the
+ *    associated memory or otherwise alter the account: the account
+ *    can now be reparented to a new location.
+ *    Note, however, that it will mark the old parents as having
+ *    been modified.
+ *
+ * Both of the above routines are private routines, since they are slightly
+ * dangerous:  If the removed group/account is not immediately reparented, 
+ * it can be lost, i.e. turn into a memory leak.  If the GUI or other engine
+ * user needs to move an account or group from here to there, it should use
+ * the 'Insert' routines, such as xaccGroupInsertAccount(), to make the move.
+ * The 'Insert' routines will automatically remove the account from its
+ * previous location.
+ */
+
+void    xaccAccountRemoveGroup (Account *acc);
+void    xaccGroupRemoveAccount (AccountGroup *grp, Account *account);
+
+/*
+ * The xaccFreeAccountGroup() subroutine will  ...
+ * 
+ */
+void     xaccFreeAccountGroup (AccountGroup *account_group);
+
 #endif

src/engine/gnc-book.c

@@ -114,13 +114,9 @@ gnc_book_destroy (GNCBook *book)
   if (!book) return;
 
   gnc_engine_generate_event (&book->guid, GNC_EVENT_DESTROY);
-  xaccRemoveEntity (book->entity_table, &book->guid);
 
-  /* mark the accounts as being freed
-   * to avoid tons of balance recomputations. */
-  xaccGroupMarkDoFree (book->topgroup);
-
-  xaccFreeAccountGroup (book->topgroup);
+  xaccAccountGroupBeginEdit (book->topgroup);
+  xaccAccountGroupDestroy (book->topgroup);
   book->topgroup = NULL;
 
   gnc_pricedb_destroy (book->pricedb);
@@ -131,6 +127,7 @@ gnc_book_destroy (GNCBook *book)
 
   /* FIXME: destroy SX data members here, too */
 
+  xaccRemoveEntity (book->entity_table, &book->guid);
   xaccEntityTableDestroy (book->entity_table);
   book->entity_table = NULL;
 

src/engine/gw-engine-spec.scm

@@ -1263,11 +1263,11 @@ children to this account.")
 
   (gw:wrap-function
    mod
-   'gnc:free-account-group
+   'gnc:account-group-destroy
    '<gw:void>
-   "xaccFreeAccountGroup"
+   "xaccAccountGroupDestroy"
    '((<gnc:AccountGroup*> g))
-   "Free an account group.")
+   "Free an account group. (Must call gnc:account-group-begin-edit first)")
 
   (gw:wrap-function
    mod

src/engine/test/test-group-vs-book.c

@@ -2,7 +2,7 @@
 #include <glib.h>
 #include <guile/gh.h>
 
-#include "Group.h"
+#include "GroupP.h"
 #include "GNCIdP.h"
 #include "TransLog.h"
 #include "gnc-book.h"

src/gnome/druid-hierarchy.c

@@ -557,7 +557,8 @@ delete_our_final_group (void)
 {
   if (our_final_group != NULL)
   {
-    xaccFreeAccountGroup (our_final_group);
+    xaccAccountGroupBeginEdit (our_final_group);
+    xaccAccountGroupDestroy (our_final_group);
     our_final_group = NULL;
   }
 }

src/import-export/qif-import/qif-merge-groups.scm

@@ -140,5 +140,6 @@
 (define (gnc:group-catenate-and-merge old-group new-group)
   ;; stuff the new accounts into the old group and merge the accounts
   (gnc:group-concat-group old-group new-group)
-  (gnc:free-account-group new-group)
+  (gnc:account-group-begin-edit new-group)
+  (gnc:account-group-destroy new-group)
   (gnc:group-merge-accounts old-group))