Menu
▾
▴
[Teem-commit] SF.net SVN: teem:[7253] teem/trunk/src/biff/README. txt
|
From: <kin...@us...> - 2025-04-14 11:09:56
|
Revision: 7253
http://sourceforge.net/p/teem/code/7253
Author: kindlmann
Date: 2025-04-14 11:09:38 +0000 (Mon, 14 Apr 2025)
Log Message:
-----------
now with 90 column lines
Modified Paths:
--------------
teem/trunk/src/biff/README.txt
Modified: teem/trunk/src/biff/README.txt
===================================================================
--- teem/trunk/src/biff/README.txt 2025-04-14 11:08:16 UTC (rev 7252)
+++ teem/trunk/src/biff/README.txt 2025-04-14 11:09:38 UTC (rev 7253)
@@ -1,27 +1,25 @@
All about /* Biff: */ annotations (new with Teem 1.13)
-teem/src/_util/scan-symbols.py -biff (the "biff auto-scan") will scrutinize
-Teem source code to look at how it uses biff. This analysis creates parsable
-annotations of function definitions to automate whether and how biffGet{Done}
-is called in response to an error (in, say, a Python wrapper), as follows.
+teem/src/_util/scan-symbols.py -biff (the "biff auto-scan") will scrutinize Teem source
+code to look at how it uses biff. This analysis creates parsable annotations of function
+definitions to automate whether and how biffGet{Done} is called in response to an error
+(in, say, a Python wrapper), as follows.
-Even though these annotations were motivated by the needs of Python wrapping
-(which is only wrapping things in the public API), GLK decided to also do these
-annotations for "private" functions (which are are available for linking in the
-library, but are declared in privateLib.h rather than lib.h), and even for
-static functions that do use biff. The idea is that this is potentially useful
-information for further analysis or for human coding, and its better to err on
-the side of more info, discretely packaged, when the quality/correctness of the
-info is high.
+Even though these annotations were motivated by the needs of Python wrapping (which is
+only wrapping things in the public API), GLK decided to also do these annotations for
+"private" functions (which are are available for linking in the library, but are declared
+in privateLib.h rather than lib.h), and even for static functions that do use biff. The
+idea is that this is potentially useful information for further analysis or for human
+coding, and its better to err on the side of more info, discretely packaged, when the
+quality/correctness of the info is high.
-NOTE that the Biff annotation on a function currently reflects a simplistic
-textual analysis of that function code, saying "it looks like this function
-uses biff in this way." This is not based on any proper parsing of the code
-AST, so calls to biff could be hidden behind a #define, and there is certainly
-no way to know (without execution) whether any other functions called from
-this function used biff. The formatting of the newly adopted clang-format
-is a big help. In any case this seems adequate for Teem's Python wrapping error
-handling.
+NOTE that the Biff annotation on a function currently reflects a simplistic textual
+analysis of that function code, saying "it looks like this function uses biff in this
+way." This is not based on any proper parsing of the code AST, so calls to biff could be
+hidden behind a #define, and there is certainly no way to know (without execution)
+whether any other functions called from this function used biff. The formatting of the
+newly adopted clang-format is a big help. In any case this seems adequate for Teem's
+Python wrapping error handling.
Here is an example annotation from teem/src/nrrd/subset.c
@@ -28,9 +26,9 @@
int /* Biff: 1 */
nrrdSlice(Nrrd *nout, const Nrrd *cnin, unsigned int saxi, size_t pos) {
-The annotations are a one-line comment, always on the line with the function
-return type, which is above the function name (this formatting is enforced by
-new use of clang-format).
+The annotations are a one-line comment, always on the line with the function return type,
+which is above the function name (this formatting is enforced by new use of
+clang-format).
** NOTE that in Teem code, the remainder of the line after the function return
** type (with the function name on the next line) is reserved for these kinds
** of annotations. Human-written comments about the return type/qualifers need
@@ -45,49 +43,42 @@
teem/src/_util/scan-symbols.py -biff *only* produces Biff? annotations.
--- Optional:
-"(private)" : this function is private (as described above). Otherwise, from
-the qualifiers on the return type of the function (the same line as this
-annotation), "static" will mean that the function is static, while not having
-"static" (and absent "(private)"), this is declared in lib.h and intended for
-external linkage. Such "private" functions probably aren't even in a python
-wrapper, but the fact of being private is nice to record once known, since you
-can't tell by looking at a function definition where it has been
-declared. Despite the tendency, there is no iron rule in Teem code that private
+"(private)" : this function is private (as described above). Otherwise, from the
+qualifiers on the return type of the function (the same line as this annotation),
+"static" will mean that the function is static, while not having "static" (and absent
+"(private)"), this is declared in lib.h and intended for external linkage. Such "private"
+functions probably aren't even in a python wrapper, but the fact of being private is nice
+to record once known, since you can't tell by looking at a function definition where it
+has been declared. Despite the tendency, there is no iron rule in Teem code that private
function names start with a single "_".
--- Required:
- "<val>" : The return value <val> indicates a biff-reported error, i.e., if
- the function returns <val> then someone needs to retrieve the biff
- error message. <val> must not contain '|', ':', or whitespace, and
- it cannot be "nope" nor "maybe". <val> is just a string (since it
- is in a comment), but hopfully it is parsable as the function return
- type (on this same line, before the comment containing this
- annotation). Simple integers are easy, but it could get trickier:
- example returns (currently used in Teem) include NULL, EOF,
- AIR_FALSE, AIR_NAN, UINT_MAX, Z_STREAM_ERROR, and
- nrrdField_unknown. The point is: be prepared to do some work if
- you're in the business of parsing and acting on Biff annotations.
-or "<v1>|<v2>" : A return value of either <v1> or <v2> indicates an error has
- been recorded in biff
-or "<v1>|<v2>|<v3>" : Error values are <v1> or <v2> or <v3>
- (and so on)
-or "maybe:<N>:<val>" : This function uses something like biffMaybeAddf(), which
- may or may not set a biff error message, depending on the value of
- one of the function parameters (always called "useBiff", as enforced
- by biff auto-scan). useBiff is the Nth function parameter, in the
- *1*-based numbering of the function parameters.
-or "nope" : This function does not use biff. The function may usefully
- communicate something about how things went wrong by a returning
- one of some possible error return values, but that isn't documented
- here because it doesn't involve biff. (Why "nope": it won't be
- confused for anything else, and GLK had just seen the excellent
- Jordan Peele movie of the same name)
+ "<val>" : The return value <val> indicates a biff-reported error, i.e., if the function
+ returns <val> then someone needs to retrieve the biff error message.
+ <val> must not contain '|', ':', or whitespace, and cannot be "nope" or "maybe"
+ <val> is just a string (since it is in a comment), but hopfully it is parsable
+ as the function return type (on this same line, before the comment containing
+ this annotation). Simple integers are easy, but it could get trickier: example
+ returns (currently used in Teem) include NULL, EOF, AIR_FALSE, AIR_NAN,
+ UINT_MAX, Z_STREAM_ERROR, and nrrdField_unknown. The point is: be prepared to
+ do some work if you're trying to parse and act on Biff annotations.
+or "<v1>|<v2>" : A return value of either <v1> or <v2> indicates an error has been
+ recorded in biff
+or "<v1>|<v2>|<v3>" : Error values are <v1> or <v2> or <v3> (and so on)
+or "maybe:<N>:<val>" : This function uses something like biffMaybeAddf(), which may or
+ may not set a biff error message, depending on the value of one of the
+ function parameters (always called "useBiff", as enforced by biff auto-scan).
+ useBiff is the Nth function parameter, in the *1*-based numbering of the
+ function parameters.
+or "nope" : This function does not use biff. The function may usefully communicate
+ something about how things went wrong by a returning one of some possible
+ error return values, but that isn't documented here because it doesn't
+ involve biff. (Why "nope": it won't be confused for anything else, and GLK had
+ just seen the excellent Jordan Peele movie of the same name)
--- Optional:
# <comments> : anything after a '#' is ignored by an annotation parser
-These annotiations are parsed and consumed by teem/python/cffi/
-
Other examples:
int /* Biff: (private) maybe:2:nrrdField_unknown */
@@ -101,7 +92,13 @@
grep 'Biff:' */*.c | cut -d: -f 2- | cut -d/ -f 2- | cut -d' ' -f 2- | cut -d\* -f 1 | sort | uniq
-Some notes on how GLK creates the annotations, for example for gage:
+For context: the Biff: annotations are created with the help of
+../_util/scan-symbols.py, which is re-run as needed when the API changes,
+and prior to releases. Then, the Biff: annotations are ready by
+../_util/gen_biffdata.py, which repackages the info and save it into
+../../python/cffi/biffdata/*.csv, one file per Teem library.
+
+Some further notes on how GLK creates the annotations, for example for gage:
GLK has his teem source checkout in ~/teem.
From the ~/teem/src/_util directory:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
