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

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

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 86 bytes --]

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

ok?
Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 4479 bytes --]

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
 

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

[Eli Zaretskii]

> Date: Sun, 15 Feb 2004 14:01:41 -0500
> From: Andrew Cagney <cagney@gnu.org>
> 
> Per my e-mail to markk, this updates the doco to reflect current reality.
> 
> ok?

Yes, but...

> +Any memory required by the @var{init} function should be allocated using
> +@var{gdbarch_obstack_zalloc}.

`gdbarch_obstack_zalloc' is not a parameter, but a true literal
symbol, so it should be in @code, not in @var.

>  @deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})

`handle' should be in @var here, I think.

> +Set the uninitialized (NULL) data-pointer corresponding to @var{handle}
> +to the non-NULL @var{pointer} value.

Both `NULL's should be in @code.

Also, is it guaranteed that uninitialized pointers have a NULL value?
In general, that's not true, but perhaps in the context of gdbarch it
is, I just don't know.

Thanks.

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

[Andrew Cagney]

>> +Set the uninitialized (NULL) data-pointer corresponding to @var{handle}
>> +to the non-NULL @var{pointer} value.
> 
> 
> Both `NULL's should be in @code.
> 
> Also, is it guaranteed that uninitialized pointers have a NULL value?
> In general, that's not true, but perhaps in the context of gdbarch it
> is, I just don't know.

In general no, but here, yes.  Perhaphs:

"Set the still @code{NULL} data-pointer ...."

Andrew

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

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 867 bytes --]


> Yes, but...

I've committed the attached.

>>> +Any memory required by the @var{init} function should be allocated using
>>> +@var{gdbarch_obstack_zalloc}.
> 
> 
> `gdbarch_obstack_zalloc' is not a parameter, but a true literal
> symbol, so it should be in @code, not in @var.
> 
> 
>>>  @deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
> 
> 
> `handle' should be in @var here, I think.
> 
> 
>>> +Set the uninitialized (NULL) data-pointer corresponding to @var{handle}
>>> +to the non-NULL @var{pointer} value.
> 
> 
> Both `NULL's should be in @code.
> 
> Also, is it guaranteed that uninitialized pointers have a NULL value?
> In general, that's not true, but perhaps in the context of gdbarch it
> is, I just don't know.

I changed it to: "Set the still @code{NULL} data-pointer ..."

Andrew


[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 4609 bytes --]

2004-02-26  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.189
diff -u -r1.189 gdbint.texinfo
--- gdbint.texinfo	24 Feb 2004 15:41:29 -0000	1.189
+++ gdbint.texinfo	26 Feb 2004 20:48:35 -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 @code{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
 
@@ -4958,35 +4952,37 @@
 
 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.
+@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{handle}, void *@var{pointer})
+Set the still @code{NULL} data-pointer corresponding to @var{handle}
+to the non-@code{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