New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
OSSL_TRACE: enhance documentation and fix doc-nit errors #9224
Closed
Closed
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,11 +3,17 @@ | |
=head1 NAME | ||
|
||
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, | ||
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9 | ||
OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL, | ||
OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4, | ||
OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9, | ||
OSSL_TRACEV, | ||
OSSL_TRACE_ENABLED | ||
- OpenSSL Tracing API | ||
|
||
=head1 SYNOPSIS | ||
|
||
=for comment generic | ||
|
||
#include <openssl/trace.h> | ||
|
||
int OSSL_trace_enabled(int category); | ||
|
@@ -17,7 +23,13 @@ OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9 | |
|
||
/* trace group macros */ | ||
OSSL_TRACE_BEGIN(category) { | ||
... | ||
... | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Relative indentation was corrected from +3 to +4 characters. |
||
if (some_error) { | ||
/* Leave trace group prematurely in case of an error */ | ||
OSSL_TRACE_CANCEL(category); | ||
goto err; | ||
} | ||
... | ||
} OSSL_TRACE_END(category); | ||
|
||
/* one-shot trace macros */ | ||
|
@@ -26,6 +38,10 @@ OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9 | |
... | ||
OSSL_TRACE9(category, format, arg1, ..., arg9) | ||
|
||
/* check whether a trace category is enabled */ | ||
if (OSSL_TRACE_ENABLED(category)) { | ||
... | ||
} | ||
|
||
=head1 DESCRIPTION | ||
|
||
|
@@ -113,7 +129,7 @@ jumping out of a trace section: | |
|
||
OSSL_TRACE_BEGIN(TLS) { | ||
|
||
if (condition) { | ||
if (some_error) { | ||
OSSL_TRACE_CANCEL(TLS); | ||
goto err; | ||
} | ||
|
@@ -126,7 +142,7 @@ This will normally expand to: | |
do { | ||
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); | ||
if (trc_out != NULL) { | ||
if (condition) { | ||
if (some_error) { | ||
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); | ||
goto err; | ||
} | ||
|
@@ -136,26 +152,71 @@ This will normally expand to: | |
} while (0); | ||
|
||
|
||
C<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> are one-shot macros which essentially wrap | ||
a single BIO_printf() into a tracing group. | ||
C<OSSL_TRACE()> and C<OSSL_TRACE1()>, C<OSSL_TRACE2()>, ... C<OSSL_TRACE9()> are | ||
so-called one-shot macros: | ||
|
||
The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output. | ||
|
||
The macro call C<OSSL_TRACEn(category, format, arg1, ..., argn)> produces | ||
printf-style trace output with n format field arguments (n=1,...,9). | ||
It expands to: | ||
|
||
OSSL_TRACE_BEGIN(category) { | ||
BIO_printf(trc_out, format, arg1, ..., argN) | ||
} OSSL_TRACE_END(category) | ||
|
||
Internally, all one-shot macros are implemented using a generic C<OSSL_TRACEV()> | ||
macro, since C90 does not support variadic macros. This helper macro has a rather | ||
weird synopsis and should not be used directly. | ||
|
||
The C<OSSL_TRACE_ENABLED(category)> macro can be used to conditionally execute | ||
some code only if a specific trace category is enabled. | ||
In some situations this is simpler than entering a trace section using | ||
C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)>. | ||
For example, the code | ||
|
||
The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to: | ||
if (OSSL_TRACE_ENABLED(TLS)) { | ||
... | ||
} | ||
|
||
OSSL_TRACE_BEGIN(category) { | ||
BIO_printf(trc_out, format, arg1, ..., argN) | ||
} OSSL_TRACE_END(category) | ||
expands to | ||
|
||
if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) { | ||
... | ||
} | ||
|
||
=head1 NOTES | ||
|
||
It is advisable to always check that a trace type is enabled with | ||
OSSL_trace_enabled() before generating any output, for example: | ||
If producing the trace output requires carrying out auxiliary calculations, | ||
this auxiliary code should be placed inside a conditional block which is | ||
executed only if the trace category is enabled. | ||
|
||
The most natural way to do this is to place the code inside the trace section | ||
itself because it already introduces such a conditional block. | ||
|
||
OSSL_TRACE_BEGIN(TLS) { | ||
int var = do_some_auxiliary_calculation(); | ||
|
||
BIO_printf(trc_out, "var = %d\n", var); | ||
|
||
} OSSL_TRACE_END(TLS); | ||
|
||
In some cases it is more advantageous to use a simple conditional group instead | ||
of a trace section. This is the case if calculations and tracing happen in | ||
different locations of the code, or if the calculations are so time consuming | ||
that placing them inside a (critical) trace section would create too much | ||
contention. | ||
|
||
if (OSSL_TRACE_ENABLED(TLS)) { | ||
int var = do_some_auxiliary_calculation(); | ||
|
||
OSSL_TRACE1("var = %d\n", var); | ||
} | ||
|
||
if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) { | ||
BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); | ||
BIO_printf(trace, "FOO %d\n", somevalue); | ||
BIO_dump(trace, somememory, somememory_l); | ||
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace); | ||
} | ||
Note however that premature optimization of tracing code is in general futile | ||
and it's better to keep the tracing code as simple as possible. | ||
Because most often the limiting factor for the application's speed is the time | ||
it takes to print the trace output, not to calculate it. | ||
|
||
=head2 Configure Tracing | ||
|
||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually, this line disables the synopsis check completely, which is inconvenient when additional symbols are added later on to the pod file. Of course, I can remove the comment line temporarily to get the errors back, but it would be nicer if one could add a specific exclusion list (here:
OSSL_TRACEV, OSSL_TRACE3, OSSL_TRACE4, ... OSSL_TRACE8
).@levitte do you think this would be a useful feature? If yes, I could raise an issue with a feature request for it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have had similar thoughts, but more on a section basis (and we should have our own keyword instead of piggy-backing on comment)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a feature request in #9226.