Erik Huelsmann wrote:
>
> Ok, I took Gregs and your comments and changed the patch. I also took the
> liberty of movig the README.errors file into HACKING. Could you have a look at
> the additions to the section Exception handling? Thanks!
>
> If nobody objects, I'll commit this patch in a few days.
A few more points mentioned below, mostly trivial; otherwise +1.
- Julian
> Index: HACKING
> ===================================================================
> --- HACKING (revision 7945)
> +++ HACKING (working copy)
> @@ -561,6 +604,113 @@
>
>
>
> +Exception handling
> +==================
> +
> +OK, here's how to use exceptions in Subversion.
> +
> +1. Exceptions are stored in svn_error_t structures:
> +
> +typedef struct svn_error
> +{
> + ap_status_t apr_err; /* APR error value, possibly SVN_ custom err */
apr_status_t
> + int src_err; /* native error code (e.g. errno, h_errno...) */
That is not a member of svn_error.
> + const char *message; /* details from producer of error */
> + struct svn_error *child; /* ptr to the error we "wrap" */
> + ap_pool_t *pool; /* place to generate message strings from */
There are also "file" and "line" members.
> +
> +} svn_error_t;
> +
> +2. If you are the *original* creator of an error, you would do
> + something like this:
> +
> + return (svn_create_error ((ap_status_t) err,
return (svn_create_error (SVN_ERR_FOO,
> + NULL,
> + "User not permitted to write file");
> +
> +
> + NOTICE the NULL field... indicating that this error has no child,
> + i.e. it is the bottom-most error.
> +
> + A section on writing error messages can be found elsewhere in this
> + document under the title 'Error message conventions'.
> +
> + Subversion internally uses utf-8 to store its data. This also applies
UTF-8
> + to the 'message' string. APR is assumed to return its data in the current
> + locale, so any text returned by APR needs conversion to UTF-8 before
> + inclusion in the message string.
Since blank lines are used to separate paragraphs, it would be nice also to have blank lines between subsections:
> +3. If you *receive* an error, you have three choices:
blank line
> + a) Handle the error yourself. Use either your own code, or just
> + call the primitive svn_handle_error(err). (This routine unwinds
> + the error stack and prints out messages.)
> +
> + When your routine receives an error which it intends to ignore or
> + handle itself, be sure to clean it up using svn_error_clear(). Any
> + time such an error is not cleared constitutes a *memory leak*.
blank line
> + b) Throw the error upwards, unmodified:
> +
> + error = some_routine (foo);
[...]
> + which does the same thing:
> +
> + SVN_ERR (some_routine (foo));
blank line
> + c) Throw the error upwards, wrapping it in a new error structure
> + by including it as the "child" argument:
> +
> + error = some_routine (foo);
[...]
> + Resources associated with pools are:
blank line
> + * Memory
blank line
> + * Files
> + All files opened with apr_file_open are closed at pool
[...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Dec 8 15:37:08 2003