From c972e253abc34f8bd02f6ade74e7999a2b6d8a08 Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Sat, 8 Mar 2014 22:11:34 +0200 Subject: Update doc on API memory allocation, add to NEWS. --- NEWS | 4 + doc/ChangeLog | 5 ++ doc/gawk.info | 274 +++++++++++++++++++++++++++++--------------------------- doc/gawk.texi | 31 +++++-- doc/gawktexi.in | 31 +++++-- 5 files changed, 199 insertions(+), 146 deletions(-) diff --git a/NEWS b/NEWS index eb7651b0..50b88a97 100644 --- a/NEWS +++ b/NEWS @@ -36,6 +36,10 @@ is now generated by a DCL script. Also, the extension facility works and several of the extensions can be built and used. Currently, the extension facility only works on Alpha and Itanium. +12. The API now provides functions pointers for malloc(), calloc(), +realloc() and free(), to insure that the same memory allocation +functions are always used. This bumps the minor version by one. + XXX. A number of bugs have been fixed. See the ChangeLog. Changes from 4.0.2 to 4.1.0 diff --git a/doc/ChangeLog b/doc/ChangeLog index 085ba317..99b81306 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2014-03-08 Arnold D. Robbins + + * gawktexi.in: Minor edits to the discussion of the memory allocation + functions. + 2014-03-08 Andrew J. Schorr * gawktexi.in: Document new extension API functions api_malloc, diff --git a/doc/gawk.info b/doc/gawk.info index 799d1c11..9a569829 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -21783,6 +21783,8 @@ operations: * Symbol table access: retrieving a global variable, creating one, or changing one. + * Allocating, reallocating, and releasing memory. + * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -21838,8 +21840,8 @@ operations: * All pointers filled in by `gawk' are to memory managed by `gawk' and should be treated by the extension as read-only. Memory for _all_ strings passed into `gawk' from the extension _must_ come - from calling the api-provided function pointers `api_malloc()', - `api_calloc()' or `api_realloc()' and is managed by `gawk' from + from calling the API-provided function pointers `api_malloc()', + `api_calloc()' or `api_realloc()', and is managed by `gawk' from then on. * The API defines several simple `struct's that map values as seen @@ -21913,7 +21915,7 @@ that use them. This represents a mutable string. `gawk' owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. *Such memory must come from calling the - api-provided function pointers `api_malloc()', `api_calloc()', or + API-provided function pointers `api_malloc()', `api_calloc()', or `api_realloc()'!* As mentioned earlier, strings are maintained using the current @@ -22058,7 +22060,7 @@ File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Function --------------------------------------------------------- The API provides a number of "memory allocation" functions for -allocating memory that can be passed to gawk, as well as a number of +allocating memory that can be passed to `gawk', as well as a number of convenience macros. `void *gawk_malloc(size_t size);' @@ -22078,8 +22080,14 @@ convenience macros. allocated with `gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. + The API has to provide these functions because it is possible for an +extension to be compiled and linked against a different version of the +C library than was used for the `gawk' executable.(1) If `gawk' were to +use its version of `free()' when the memory came from an unrelated +version of `malloc()', unexpected behavior would likely result. + Two convenience macros may be used for allocating storage from the -api-provided function pointers `api_malloc()' and `api_realloc()'. If +API-provided function pointers `api_malloc()' and `api_realloc()'. If the allocation fails, they cause `gawk' to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @@ -22115,6 +22123,11 @@ not return a value. `api_malloc()'. The arguments are the same as for the `emalloc()' macro. + ---------- Footnotes ---------- + + (1) This is more common on MS-Windows systems, but can happen on +Unix-like systems as well. +  File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Memory Allocation Functions, Up: Extension API Description @@ -33226,130 +33239,131 @@ Ref: load-new-function874241 Ref: call-new-function875236 Node: Extension API Description877251 Node: Extension API Functions Introduction878538 -Node: General Data Types883410 -Ref: General Data Types-Footnote-1889105 -Node: Requesting Values889404 -Ref: table-value-types-returned890141 -Node: Memory Allocation Functions891095 -Node: Constructor Functions893456 -Node: Registration Functions895214 -Node: Extension Functions895899 -Node: Exit Callback Functions898201 -Node: Extension Version String899450 -Node: Input Parsers900100 -Node: Output Wrappers909857 -Node: Two-way processors914367 -Node: Printing Messages916575 -Ref: Printing Messages-Footnote-1917652 -Node: Updating `ERRNO'917804 -Node: Accessing Parameters918543 -Node: Symbol Table Access919773 -Node: Symbol table by name920287 -Node: Symbol table by cookie922036 -Ref: Symbol table by cookie-Footnote-1926168 -Node: Cached values926231 -Ref: Cached values-Footnote-1929721 -Node: Array Manipulation929812 -Ref: Array Manipulation-Footnote-1930910 -Node: Array Data Types930949 -Ref: Array Data Types-Footnote-1933652 -Node: Array Functions933744 -Node: Flattening Arrays937580 -Node: Creating Arrays944432 -Node: Extension API Variables949157 -Node: Extension Versioning949793 -Node: Extension API Informational Variables951694 -Node: Extension API Boilerplate952780 -Node: Finding Extensions956584 -Node: Extension Example957144 -Node: Internal File Description957874 -Node: Internal File Ops961965 -Ref: Internal File Ops-Footnote-1973474 -Node: Using Internal File Ops973614 -Ref: Using Internal File Ops-Footnote-1975967 -Node: Extension Samples976233 -Node: Extension Sample File Functions977757 -Node: Extension Sample Fnmatch986242 -Node: Extension Sample Fork988011 -Node: Extension Sample Inplace989224 -Node: Extension Sample Ord991002 -Node: Extension Sample Readdir991838 -Node: Extension Sample Revout993370 -Node: Extension Sample Rev2way993963 -Node: Extension Sample Read write array994653 -Node: Extension Sample Readfile996536 -Node: Extension Sample API Tests997354 -Node: Extension Sample Time997879 -Node: gawkextlib999243 -Node: Language History1002024 -Node: V7/SVR3.11003617 -Node: SVR41005937 -Node: POSIX1007379 -Node: BTL1008765 -Node: POSIX/GNU1009499 -Node: Feature History1015098 -Node: Common Extensions1028074 -Node: Ranges and Locales1029386 -Ref: Ranges and Locales-Footnote-11034003 -Ref: Ranges and Locales-Footnote-21034030 -Ref: Ranges and Locales-Footnote-31034264 -Node: Contributors1034485 -Node: Installation1039630 -Node: Gawk Distribution1040524 -Node: Getting1041008 -Node: Extracting1041834 -Node: Distribution contents1043526 -Node: Unix Installation1049231 -Node: Quick Installation1049848 -Node: Additional Configuration Options1052294 -Node: Configuration Philosophy1054030 -Node: Non-Unix Installation1056384 -Node: PC Installation1056842 -Node: PC Binary Installation1058141 -Node: PC Compiling1059989 -Node: PC Testing1062933 -Node: PC Using1064109 -Node: Cygwin1068277 -Node: MSYS1069086 -Node: VMS Installation1069600 -Node: VMS Compilation1070364 -Ref: VMS Compilation-Footnote-11071616 -Node: VMS Dynamic Extensions1071674 -Node: VMS Installation Details1073047 -Node: VMS Running1075298 -Node: VMS GNV1078132 -Node: VMS Old Gawk1078855 -Node: Bugs1079325 -Node: Other Versions1083243 -Node: Notes1089327 -Node: Compatibility Mode1090127 -Node: Additions1090910 -Node: Accessing The Source1091837 -Node: Adding Code1093277 -Node: New Ports1099322 -Node: Derived Files1103457 -Ref: Derived Files-Footnote-11108778 -Ref: Derived Files-Footnote-21108812 -Ref: Derived Files-Footnote-31109412 -Node: Future Extensions1109510 -Node: Implementation Limitations1110093 -Node: Extension Design1111345 -Node: Old Extension Problems1112499 -Ref: Old Extension Problems-Footnote-11114007 -Node: Extension New Mechanism Goals1114064 -Ref: Extension New Mechanism Goals-Footnote-11117429 -Node: Extension Other Design Decisions1117615 -Node: Extension Future Growth1119721 -Node: Old Extension Mechanism1120557 -Node: Basic Concepts1122297 -Node: Basic High Level1122978 -Ref: figure-general-flow1123249 -Ref: figure-process-flow1123848 -Ref: Basic High Level-Footnote-11127077 -Node: Basic Data Typing1127262 -Node: Glossary1130617 -Node: Copying1156079 -Node: GNU Free Documentation License1193636 -Node: Index1218773 +Node: General Data Types883465 +Ref: General Data Types-Footnote-1889160 +Node: Requesting Values889459 +Ref: table-value-types-returned890196 +Node: Memory Allocation Functions891150 +Ref: Memory Allocation Functions-Footnote-1893896 +Node: Constructor Functions893992 +Node: Registration Functions895750 +Node: Extension Functions896435 +Node: Exit Callback Functions898737 +Node: Extension Version String899986 +Node: Input Parsers900636 +Node: Output Wrappers910393 +Node: Two-way processors914903 +Node: Printing Messages917111 +Ref: Printing Messages-Footnote-1918188 +Node: Updating `ERRNO'918340 +Node: Accessing Parameters919079 +Node: Symbol Table Access920309 +Node: Symbol table by name920823 +Node: Symbol table by cookie922572 +Ref: Symbol table by cookie-Footnote-1926704 +Node: Cached values926767 +Ref: Cached values-Footnote-1930257 +Node: Array Manipulation930348 +Ref: Array Manipulation-Footnote-1931446 +Node: Array Data Types931485 +Ref: Array Data Types-Footnote-1934188 +Node: Array Functions934280 +Node: Flattening Arrays938116 +Node: Creating Arrays944968 +Node: Extension API Variables949693 +Node: Extension Versioning950329 +Node: Extension API Informational Variables952230 +Node: Extension API Boilerplate953316 +Node: Finding Extensions957120 +Node: Extension Example957680 +Node: Internal File Description958410 +Node: Internal File Ops962501 +Ref: Internal File Ops-Footnote-1974010 +Node: Using Internal File Ops974150 +Ref: Using Internal File Ops-Footnote-1976503 +Node: Extension Samples976769 +Node: Extension Sample File Functions978293 +Node: Extension Sample Fnmatch986778 +Node: Extension Sample Fork988547 +Node: Extension Sample Inplace989760 +Node: Extension Sample Ord991538 +Node: Extension Sample Readdir992374 +Node: Extension Sample Revout993906 +Node: Extension Sample Rev2way994499 +Node: Extension Sample Read write array995189 +Node: Extension Sample Readfile997072 +Node: Extension Sample API Tests997890 +Node: Extension Sample Time998415 +Node: gawkextlib999779 +Node: Language History1002560 +Node: V7/SVR3.11004153 +Node: SVR41006473 +Node: POSIX1007915 +Node: BTL1009301 +Node: POSIX/GNU1010035 +Node: Feature History1015634 +Node: Common Extensions1028610 +Node: Ranges and Locales1029922 +Ref: Ranges and Locales-Footnote-11034539 +Ref: Ranges and Locales-Footnote-21034566 +Ref: Ranges and Locales-Footnote-31034800 +Node: Contributors1035021 +Node: Installation1040166 +Node: Gawk Distribution1041060 +Node: Getting1041544 +Node: Extracting1042370 +Node: Distribution contents1044062 +Node: Unix Installation1049767 +Node: Quick Installation1050384 +Node: Additional Configuration Options1052830 +Node: Configuration Philosophy1054566 +Node: Non-Unix Installation1056920 +Node: PC Installation1057378 +Node: PC Binary Installation1058677 +Node: PC Compiling1060525 +Node: PC Testing1063469 +Node: PC Using1064645 +Node: Cygwin1068813 +Node: MSYS1069622 +Node: VMS Installation1070136 +Node: VMS Compilation1070900 +Ref: VMS Compilation-Footnote-11072152 +Node: VMS Dynamic Extensions1072210 +Node: VMS Installation Details1073583 +Node: VMS Running1075834 +Node: VMS GNV1078668 +Node: VMS Old Gawk1079391 +Node: Bugs1079861 +Node: Other Versions1083779 +Node: Notes1089863 +Node: Compatibility Mode1090663 +Node: Additions1091446 +Node: Accessing The Source1092373 +Node: Adding Code1093813 +Node: New Ports1099858 +Node: Derived Files1103993 +Ref: Derived Files-Footnote-11109314 +Ref: Derived Files-Footnote-21109348 +Ref: Derived Files-Footnote-31109948 +Node: Future Extensions1110046 +Node: Implementation Limitations1110629 +Node: Extension Design1111881 +Node: Old Extension Problems1113035 +Ref: Old Extension Problems-Footnote-11114543 +Node: Extension New Mechanism Goals1114600 +Ref: Extension New Mechanism Goals-Footnote-11117965 +Node: Extension Other Design Decisions1118151 +Node: Extension Future Growth1120257 +Node: Old Extension Mechanism1121093 +Node: Basic Concepts1122833 +Node: Basic High Level1123514 +Ref: figure-general-flow1123785 +Ref: figure-process-flow1124384 +Ref: Basic High Level-Footnote-11127613 +Node: Basic Data Typing1127798 +Node: Glossary1131153 +Node: Copying1156615 +Node: GNU Free Documentation License1194172 +Node: Index1219309  End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index f0c7d6e6..09beef82 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -29631,6 +29631,9 @@ an array. Symbol table access: retrieving a global variable, creating one, or changing one. +@item +Allocating, reallocating, and releasing memory. + @item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and @@ -29701,8 +29704,9 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} are to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} -from the extension @emph{must} come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and is managed -by @command{gawk} from then on. +from the extension @emph{must} come from calling the API-provided function +pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}, +and is managed by @command{gawk} from then on. @item The API defines several simple @code{struct}s that map values as seen @@ -29784,7 +29788,8 @@ A simple boolean type. This represents a mutable string. @command{gawk} owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. -@strong{Such memory must come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} +@strong{Such memory must come from calling the API-provided function +pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -29950,7 +29955,8 @@ value type, as appropriate. This behavior is summarized in @subsection Memory Allocation Functions and Convenience Macros The API provides a number of @dfn{memory allocation} functions for -allocating memory that can be passed to gawk, as well as a number of convenience macros. +allocating memory that can be passed to @command{gawk}, as well as a number of +convenience macros. @table @code @item void *gawk_malloc(size_t size); @@ -29970,10 +29976,19 @@ Call @command{gawk}-provided @code{api_free()} to release storage that was allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table - -Two convenience macros may be used for allocating storage from the api-provided function pointers @code{api_malloc()} -and @code{api_realloc()}. If the allocation fails, they cause @command{gawk} to -exit with a fatal error message. They should be used as if they were +The API has to provide these functions because it is possible +for an extension to be compiled and linked against a different +version of the C library than was used for the @command{gawk} +executable.@footnote{This is more common on MS-Windows systems, but +can happen on Unix-like systems as well.} If @command{gawk} were +to use its version of @code{free()} when the memory came from an +unrelated version of @code{malloc()}, unexpected behavior would +likely result. + +Two convenience macros may be used for allocating storage +from the API-provided function pointers @code{api_malloc()} and +@code{api_realloc()}. If the allocation fails, they cause @command{gawk} +to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @table @code diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 3720a0dc..6d7c5055 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -28772,6 +28772,9 @@ an array. Symbol table access: retrieving a global variable, creating one, or changing one. +@item +Allocating, reallocating, and releasing memory. + @item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and @@ -28842,8 +28845,9 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} are to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} -from the extension @emph{must} come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and is managed -by @command{gawk} from then on. +from the extension @emph{must} come from calling the API-provided function +pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}, +and is managed by @command{gawk} from then on. @item The API defines several simple @code{struct}s that map values as seen @@ -28925,7 +28929,8 @@ A simple boolean type. This represents a mutable string. @command{gawk} owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. -@strong{Such memory must come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} +@strong{Such memory must come from calling the API-provided function +pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -29091,7 +29096,8 @@ value type, as appropriate. This behavior is summarized in @subsection Memory Allocation Functions and Convenience Macros The API provides a number of @dfn{memory allocation} functions for -allocating memory that can be passed to gawk, as well as a number of convenience macros. +allocating memory that can be passed to @command{gawk}, as well as a number of +convenience macros. @table @code @item void *gawk_malloc(size_t size); @@ -29111,10 +29117,19 @@ Call @command{gawk}-provided @code{api_free()} to release storage that was allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table - -Two convenience macros may be used for allocating storage from the api-provided function pointers @code{api_malloc()} -and @code{api_realloc()}. If the allocation fails, they cause @command{gawk} to -exit with a fatal error message. They should be used as if they were +The API has to provide these functions because it is possible +for an extension to be compiled and linked against a different +version of the C library than was used for the @command{gawk} +executable.@footnote{This is more common on MS-Windows systems, but +can happen on Unix-like systems as well.} If @command{gawk} were +to use its version of @code{free()} when the memory came from an +unrelated version of @code{malloc()}, unexpected behavior would +likely result. + +Two convenience macros may be used for allocating storage +from the API-provided function pointers @code{api_malloc()} and +@code{api_realloc()}. If the allocation fails, they cause @command{gawk} +to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @table @code -- cgit v1.2.1