[rfa:doco] mention gdbarch_obstack_zalloc in per-module data

[Andrew Cagney <cagney at gnu dot org>]

Per my e-mail to markk, this updates the doco to reflect current reality.

ok?
Andrew

2004-02-15  Andrew Cagney  <cagney@redhat.com>

	* gdbint.texinfo (Coding): Document use of gdbarch_obstack_zalloc
	in Per-architecture module data section.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.186
diff -u -r1.186 gdbint.texinfo
--- gdbint.texinfo	14 Feb 2004 17:01:01 -0000	1.186
+++ gdbint.texinfo	15 Feb 2004 19:00:04 -0000
@@ -4879,7 +4879,7 @@
 A module registers one or more per-architecture data-pointers using the
 function @code{register_gdbarch_data}:
 
-@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
+@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init})
 
 The @var{init} function is used to obtain an initial value for a
 per-architecture data-pointer.  The function is called, after the
@@ -4888,10 +4888,9 @@
 to @code{gdbarch_data}.  A data-pointer can also be initialize
 explicitly using @code{set_gdbarch_data}.
 
-The @var{free} function is called when a data-pointer needs to be
-destroyed.  This occurs when either the corresponding @code{struct
-gdbarch} object is being destroyed or when @code{set_gdbarch_data} is
-overriding a non-@code{NULL} data-pointer value.
+Any memory required by the @var{init} function should be allocated using
+@var{gdbarch_obstack_zalloc}.  That memory is automatically released
+when the corresponding architecture is deleted.
 
 The function @code{register_gdbarch_data} returns a @code{struct
 gdbarch_data} that is used to identify the data-pointer that was added
@@ -4899,23 +4898,18 @@
 
 @end deftypefun
 
-A typical module has @code{init} and @code{free} functions of the form:
+A typical module has an @code{init} function of the form:
 
 @smallexample
+struct nozel @{ int total; @};
 static struct gdbarch_data *nozel_handle;
 static void *
 nozel_init (struct gdbarch *gdbarch)
 @{
-  struct nozel *data = XMALLOC (struct nozel);
+  struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
   @dots{}
   return data;
 @}
-@dots{}
-static void
-nozel_free (struct gdbarch *gdbarch, void *data)
-@{
-  xfree (data);
-@}
 @end smallexample
 
 Since uninitialized (@code{NULL}) data-pointers are initialized
@@ -4930,7 +4924,7 @@
 void
 _initialize_nozel (void)
 @{
-  nozel_handle = register_gdbarch_data (nozel_init, nozel_free);
+  nozel_handle = register_gdbarch_data (nozel_init);
 @dots{}
 @end smallexample
 
@@ -4959,34 +4953,36 @@
 It is also possible to directly initialize the data-pointer using:
 
 @deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
-Update the data-pointer corresponding to @var{handle} with the value of
-@var{pointer}.  If the previous data-pointer value is non-NULL, then it
-is freed using data-pointers @var{free} function.
+Set the uninitialized (NULL) data-pointer corresponding to @var{handle}
+to the non-NULL @var{pointer} value.
 @end deftypefun
 
 This function is used by modules that require a mechanism for explicitly
 setting the per-architecture data-pointer during architecture creation:
 
 @smallexample
-/* Called during architecture creation.  */
-extern void
-set_gdbarch_nozel (struct gdbarch *gdbarch,
-                   int total)
-@{
-  struct nozel *data = XMALLOC (struct nozel);
-  @dots{}
-  set_gdbarch_data (gdbarch, nozel_handle, nozel);
+/* Always return a non-NULL nozel.  */
+static struct nozel *
+gdbarch_nozel (struct gdbarch *gdbarch)
+@{
+  struct nozel *nozel = gdbarch_data (gdbarch, nozel_handle);
+  if (nozel == NULL)
+    @{
+      nozel = nozel_init (gdbarch);
+      set_gdbarch_data (gdbarch, nozel_handle, nozel);
+    @}
+  return nozel;
 @}
 @end smallexample
 
 @smallexample
-/* Default, called when nozel not set by set_gdbarch_nozel().  */
-static void *
-nozel_init (struct gdbarch *gdbarch)
+/* Called during architecture creation.  */
+extern void
+set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
 @{
-  struct nozel *default_nozel = XMALLOC (struc nozel);
+  struct nozel *data = gdbarch_nozel (gdbarch);
   @dots{}
-  return default_nozel;
+  data->total = total;
 @}
 @end smallexample
 
@@ -4994,7 +4990,7 @@
 void
 _initialize_nozel (void)
 @{
-  nozel_handle = register_gdbarch_data (nozel_init, NULL);
+  nozel_handle = register_gdbarch_data (nozel_init);
   @dots{}
 @end smallexample