doc: logging function documentation #6043
Conversation
osalyk
added
sprint goal
There was a problem hiding this comment.
Reviewed 2 of 5 files at r1, all commit messages.
Reviewable status: 2 of 5 files reviewed, 6 unresolved discussions (waiting on @osalyk)
a discussion (no related file):
Please clean up the https://github.com/pmem/pmdk/blob/master/src/include/libpmemobj/log.h from the documentation at the same time. Personally I would prefer to have it there but since we keep all of the documentation here we don't need a duplicate.
a discussion (no related file):
I am considering having a single .md file and two aliases instead of three separate man pages. Note that all of them have to have defined enum pmemobj_log_level which is a big piece of information to have it copied over and over. What do you think?
@grom72 ?
doc/Makefile line 69 at r1 (raw file):
libpmemobj/tx_xstrdup.3 libpmemobj/tx_xwcsdup.3 libpmemobj/tx_xfree.3 \ libpmemobj/pmemobj_defrag.3 libpmemobj/pmemobj_get_user_data.3 libpmemobj/pmemobj_set_user_data.3 libpmemobj/pmemobj_tx_get_user_data.3 libpmemobj/pmemobj_tx_set_user_data.3 libpmemobj/pmemobj_tx_get_failure_behavior.3 libpmemobj/pmemobj_tx_set_failure_behavior.3 \ libpmemobj/pmemobj_log_get_threshold.3.md libpmemobj/pmemobj_log_set_function.3.md libpmemobj/pmemobj_log_set_threshold.3.md
I believe this line is necessary only when you have a handcrafted .3 file.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 6 at r1 (raw file):
description: "" disclaimer: "The contents of this web site and the associated <a href=\"https://github.com/pmem\">GitHub repositories</a> are BSD-licensed open source." aliases: ["pobj_log_get_function.3.html"]
Suggestion:
pmemobj_log_get_thresholddoc/libpmemobj/pmemobj_log_get_threshold.3.md line 14 at r1 (raw file):
[comment]: <> (Copyright 2024, Intel Corporation) [comment]: <> (pmemobj_log_get_threshold.3 -- man page for get the logging threshold level)
Suggestion:
get the logging threshold leveldoc/libpmemobj/pmemobj_log_get_threshold.3.md line 31 at r1 (raw file):
```c int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_levellevel);
Suggestion:
enum pmemobj_log_level level
There was a problem hiding this comment.
Reviewable status: 1 of 6 files reviewed, 6 unresolved discussions (waiting on @grom72 and @janekmi)
a discussion (no related file):
Previously, janekmi (Jan Michalski) wrote…
Please clean up the https://github.com/pmem/pmdk/blob/master/src/include/libpmemobj/log.h from the documentation at the same time. Personally I would prefer to have it there but since we keep all of the documentation here we don't need a duplicate.
Done.
a discussion (no related file):
Previously, janekmi (Jan Michalski) wrote…
I am considering having a single .md file and two aliases instead of three separate man pages. Note that all of them have to have defined
enum pmemobj_log_levelwhich is a big piece of information to have it copied over and over. What do you think?@grom72 ?
I believe that three separate pages are more readable
doc/Makefile line 69 at r1 (raw file):
Previously, janekmi (Jan Michalski) wrote…
I believe this line is necessary only when you have a handcrafted
.3file.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 6 at r1 (raw file):
description: "" disclaimer: "The contents of this web site and the associated <a href=\"https://github.com/pmem\">GitHub repositories</a> are BSD-licensed open source." aliases: ["pobj_log_get_function.3.html"]
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 14 at r1 (raw file):
[comment]: <> (Copyright 2024, Intel Corporation) [comment]: <> (pmemobj_log_get_threshold.3 -- man page for get the logging threshold level)
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 31 at r1 (raw file):
```c int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_levellevel);
Done.
osalyk
force-pushed
the
logging_doc
branch
3 times, most recently
from
9110b92
to
f629d10
Compare
There was a problem hiding this comment.
Reviewed 5 of 5 files at r2, all commit messages.
Reviewable status: all files reviewed, 39 unresolved discussions (waiting on @osalyk)
a discussion (no related file):
Previously, osalyk (Oksana Sałyk) wrote…
I believe that three separate pages are more readable
Discussed offline. 🥊
a discussion (no related file):
It seems you are using spaces and tabs interchangeably. Please verify what is the most common in other files and apply consistently at least in these new files.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 30 at r2 (raw file):
```c int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
Suggestion:
#include <libpmemobj.h>
int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,doc/libpmemobj/pmemobj_log_get_threshold.3.md line 31 at r2 (raw file):
```c int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level level);
Sorry, didn't notice the missing asterisk when reading for the first time.
Suggestion:
enum pmemobj_log_level *leveldoc/libpmemobj/pmemobj_log_get_threshold.3.md line 36 at r2 (raw file):
# DESCRIPTION # **pmemobj_log_get_threshold**() gets the current level of the threshold.
Suggestion:
**pmemobj_log_get_threshold**() gets the current *level* of the *threshold*.doc/libpmemobj/pmemobj_log_get_threshold.3.md line 42 at r2 (raw file):
**pmemobj_log_get_threshold**() function returns 0 on success or returns a non-zero value and sets errno on failure.
Suggestion:
**pmemobj_log_get_threshold**() function returns 0 and sets the *level* value
on success. On failure, it returns a non-zero value and sets errno.
In case of failure, the *level* value is undefined.doc/libpmemobj/pmemobj_log_get_threshold.3.md line 47 at r2 (raw file):
**pmemobj_log_get_threshold**() can fail with the following errors: - EINVAL - threshold is not **CORE_LOG_THRESHOLD** nor **CORE_LOG_THRESHOLD_AUX**
Suggestion:
*threshold* is not **PMEMOBJ_LOG_THRESHOLD_AUX** nor **PMEMOBJ_LOG_THRESHOLD_AUX**doc/libpmemobj/pmemobj_log_get_threshold.3.md line 48 at r2 (raw file):
**pmemobj_log_get_threshold**() can fail with the following errors: - EINVAL - threshold is not **CORE_LOG_THRESHOLD** nor **CORE_LOG_THRESHOLD_AUX** - EINVAL - *level is NULL
Suggestion:
*level* is NULLdoc/libpmemobj/pmemobj_log_set_function.3.md line 19 at r2 (raw file):
[SYNOPSIS](#synopsis)<br /> [DESCRIPTION](#description)<br /> [RETURN VALUE](#return-value)<br />
Suggestion:
[DESCRIPTION](#description)<br />
[THE DEFAULT LOGGING FUNCTION](#the-default-logging-function)<br />
[RETURN VALUE](#return-value)<br />doc/libpmemobj/pmemobj_log_set_function.3.md line 31 at r2 (raw file):
```c #include <libpmemobj.h>
Suggestion:
#include <libpmemobj.h>doc/libpmemobj/pmemobj_log_set_function.3.md line 39 at r2 (raw file):
const char *function_name, const char *message_format, ...);
There is a bug in the typedef void pmemobj_log_function ATM. In the end, it should match the typedef void core_log_function.
FYI @grom72
Suggestion:
typedef void pmemobj_log_function(
enum pmemobj_log_level level,
const char *file_name,
const int line_no,
const char *function_name,
const char *message);doc/libpmemobj/pmemobj_log_set_function.3.md line 47 at r2 (raw file):
**pmemobj_log_set_function**() allows choosing the function which will get all the generated logging messages. The log_function can be either
Suggestion:
The *log_function* can be eitherdoc/libpmemobj/pmemobj_log_set_function.3.md line 52 at r2 (raw file):
Parameters of a user-defined log function are as follow: - **level** - the log level of the message (see **pmemobj_log_set_threshold**(3))
Suggestion:
- *level* - the log level of the message (see **pmemobj_log_set_threshold**(3))doc/libpmemobj/pmemobj_log_set_function.3.md line 55 at r2 (raw file):
- **file_name** - name of the source file where the message coming from. It could be set to NULL and in such case neither line_no nor function_name are provided.
Suggestion:
- *file_name* - name of the source file where the message coming from.
It could be set to NULL and in such case, neither *line_no* nor *function_name*
are provided.doc/libpmemobj/pmemobj_log_set_function.3.md line 57 at r2 (raw file):
in such case neither line_no nor function_name are provided. - **line_no** - the source file line where the message coming from - **function_name** - the function name where the message coming from
Suggestion:
- *line_no* - the source file line where the message coming from
- *function_name* - the function name where the message coming fromdoc/libpmemobj/pmemobj_log_set_function.3.md line 59 at r2 (raw file):
- **function_name** - the function name where the message coming from - **message_format** - **printf**(3)-like format string of the message - "..." - additional arguments of the message format string
Suggestion:
- *message* - the message stringdoc/libpmemobj/pmemobj_log_set_function.3.md line 61 at r2 (raw file):
- "..." - additional arguments of the message format string THE DEFAULT LOGGING FUNCTION
Suggestion:
# THE DEFAULT LOGGING FUNCTION #doc/libpmemobj/pmemobj_log_set_function.3.md line 62 at r2 (raw file):
THE DEFAULT LOGGING FUNCTION The initial value of the logging function is **CORE_LOG_USE_DEFAULT_FUNCTION**.
Suggestion:
PMEMOBJ_LOG_USE_DEFAULT_FUNCTIONdoc/libpmemobj/pmemobj_log_set_function.3.md line 69 at r2 (raw file):
**pmemobj_log_set_function**() function returns 0 on success or returns a non-zero value and sets errno on failure.
Suggestion:
**pmemobj_log_set_function**() function returns 0 on success or returns
a non-zero value and sets errno on failure. On failure, the logging
function remains unchanged.doc/libpmemobj/pmemobj_log_set_function.3.md line 73 at r2 (raw file):
# ERRORS # - EAGAIN - a temporary error occurred, the retry may fix the problem
Please apply as explained in case of the pmemobj_log_set_threshold() and the EAGAIN error.
Code quote:
- EAGAIN - a temporary error occurred, the retry may fix the problemdoc/libpmemobj/pmemobj_log_set_function.3.md line 77 at r2 (raw file):
# NOTE # The logging messages on the levels above the CORE_LOG_THRESHOLD level won't
Suggestion:
**PMEMOBJ_LOG_THRESHOLD**doc/libpmemobj/pmemobj_log_set_threshold.3.md line 30 at r2 (raw file):
```c #include <libpmemobj.h>
Suggestion:
#include <libpmemobj.h>doc/libpmemobj/pmemobj_log_set_threshold.3.md line 35 at r2 (raw file):
enum pmemobj_log_level level); enum log_level {
Suggestion:
pmemobj_log_leveldoc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r2 (raw file):
}; enum log_threshold {
Suggestion:
enum pmemobj_log_thresholddoc/libpmemobj/pmemobj_log_set_threshold.3.md line 49 at r2 (raw file):
PMEMOBJ_LOG_THRESHOLD_AUX, PMEMOBJ_LOG_THRESHOLD_MAX };
Since it is a C snippet I would prefer to keep types before the function referring to them, so:
- enum pmemobj_log_level
- enum pmemobj_log_threshold
- pmemobj_log_set_threshold()
Code quote:
enum log_level {
PMEMOBJ_LOG_LEVEL_HARK,
PMEMOBJ_LOG_LEVEL_FATAL,
PMEMOBJ_LOG_LEVEL_ERROR,
PMEMOBJ_LOG_LEVEL_WARNING,
PMEMOBJ_LOG_LEVEL_NOTICE,
PMEMOBJ_LOG_LEVEL_INFO,
PMEMOBJ_LOG_LEVEL_DEBUG,
};
enum log_threshold {
PMEMOBJ_LOG_THRESHOLD,
PMEMOBJ_LOG_THRESHOLD_AUX,
PMEMOBJ_LOG_THRESHOLD_MAX
};doc/libpmemobj/pmemobj_log_set_threshold.3.md line 60 at r2 (raw file):
logging messages. Messages on a higher level than the primary threshold level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress logging.
Suggestion:
level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress
logging except for the basic library info. Please see the
*PMEMOBJ_LOG_LEVEL_HARK* for details.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 61 at r2 (raw file):
level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress logging. The default value is **PMEMOBJ_LOG_WARNING**.
Suggestion:
The default value is **PMEMOBJ_LOG_WARNING**.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 63 at r2 (raw file):
The default value is **PMEMOBJ_LOG_WARNING**. - **PMEMOBJ_LOG_THRESHOLD_AUX** - the auxiliary threshold intended for use inside the logging function (please see **log_get_threshold**(3)). The logging
Suggestion:
pmemobj_log_get_thresholddoc/libpmemobj/pmemobj_log_set_threshold.3.md line 65 at r2 (raw file):
the logging function (please see **log_get_threshold**(3)). The logging function may or may not take this threshold into consideration. The default value is **PMEMOBJ_LOG_LEVEL_HARK**.
Suggestion:
the logging function (please see **log_get_threshold**(3)). A custom
logging function may or may not take this threshold into consideration depending
on the developer's needs. For the default logging function behaviour please see
*pmemobj_set_log_function*(3). The default value of this threshold is
**PMEMOBJ_LOG_LEVEL_HARK**.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 67 at r2 (raw file):
value is **PMEMOBJ_LOG_LEVEL_HARK**. Available threshold levels are defined by enum log_level:
Suggestion:
*enum pmemobj_log_level*doc/libpmemobj/pmemobj_log_set_threshold.3.md line 68 at r2 (raw file):
Available threshold levels are defined by enum log_level: - **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info
Suggestion:
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info. It is used just for
a few messages when the program is started and whenever a new logging function
is set. Please see **pmemobj_log_set_function**(3).doc/libpmemobj/pmemobj_log_set_threshold.3.md line 70 at r2 (raw file):
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info - **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the library to stop working immediately
Suggestion:
- **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the program to stop working
immediately. Sorry.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 72 at r2 (raw file):
immediately - **PMEMOBJ_LOG_LEVEL_ERROR** - an error that causes the library to stop working properly
Suggestion:
- **PMEMOBJ_LOG_LEVEL_ERROR** - an error that causes the current operation or transaction to faildoc/libpmemobj/pmemobj_log_set_threshold.3.md line 74 at r2 (raw file):
properly - **PMEMOBJ_LOG_LEVEL_WARNING** - an error that could be handled in the upper level
Suggestion:
- **PMEMOBJ_LOG_LEVEL_WARNING** - an unexpected situation that does NOT cause the current operation to faildoc/libpmemobj/pmemobj_log_set_threshold.3.md line 84 at r2 (raw file):
where **syslog**(3) is the primary destination (**PMEMOBJ_LOG_THRESHOLD** applies) whereas **stderr**(3) is the secondary destination (**PMEMOBJ_LOG_THRESHOLD_AUX** applies).
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 89 at r2 (raw file):
**pmemobj_log_set_threshold**() function returns 0 on success or returns a non-zero value and sets errno on failure.
Suggestion:
**pmemobj_log_set_threshold**() function returns 0 on success or returns
a non-zero value and sets errno on failure. On failure, the *threshold* value remains unchanged.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 96 at r2 (raw file):
- EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX** - EINVAL - level is not a value defined by enum log_level type
Suggestion:
level is not a value defined by *enum log_level* typedoc/libpmemobj/pmemobj_log_set_threshold.3.md line 97 at r2 (raw file):
**PMEMOBJ_LOG_THRESHOLD_AUX** - EINVAL - level is not a value defined by enum log_level type - EAGAIN - a temporary error occurred, the retry may fix the problem
Suggestion:
- EAGAIN - multiple threads attempted to change the *threshold* value concurrently.
A retry may fix the problem. This error is not expected when the function is
called from just one thread at a time.src/include/libpmemobj/log.h line 61 at r2 (raw file):
*/ int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
Suggestion:
int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level level);
int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level *level);src/include/libpmemobj/log.h line 84 at r2 (raw file):
/* * pmemobj_log_set_function - set the logging function */
There was a problem hiding this comment.
Reviewed 1 of 5 files at r1, 4 of 5 files at r2, all commit messages.
Reviewable status: all files reviewed, 48 unresolved discussions (waiting on @osalyk)
a discussion (no related file):
I think we should have a common file for core_log_get/set_treshold as it is done for pmemobj_ctl_get/set
a discussion (no related file):
@janekmi do we need PMEMOBJ_LOG_THRESHOLD_MAX at all?
doc/libpmemobj/.gitignore line 10 at r2 (raw file):
pmemobj_log_get_threshold.3 pmemobj_log_set_function.3 pmemobj_log_set_threshold.3
Threshold documentation for get/set operations shall be in the pmemobj_log_set_threshold.md
pmemobj_log_get_threshold.3 should have the following content:
.so pmemobj_log_set_threshold.3
Suggestion:
pmemobj_log_set_function.3
pmemobj_log_set_threshold.3doc/libpmemobj/pmemobj_log_set_function.3.md line 64 at r2 (raw file):
The initial value of the logging function is **CORE_LOG_USE_DEFAULT_FUNCTION**. This function writes messages to **syslog**(3) (the primary destination) and to **stderr**(3) (the secondary destination).
The default function is NULL ;)
@janekmi, please correct me if I'm wrong.
Suggestion:
The library provides the default logging function which writes messages to
**syslog**(3) (the primary destination) and to **stderr**(3) (the secondary
destination). This function is enabled during library initialization and can
be restored using **CORE_LOG_USE_DEFAULT_FUNCTION** value of log_function*
argument. doc/libpmemobj/pmemobj_log_set_function.3.md line 81 at r2 (raw file):
The user defined function must be thread-safe.
The library will call user defined function before returning from pmemobj_log_set_function() to deliver basic information about the library:
"src version: 2.y.z"
"compiled with support for shutdown state"
"compiled with libndctl 63+"
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 58 at r2 (raw file):
Available thresholds are: - **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired logging messages. Messages on a higher level than the primary threshold
What does it mean a higher level?
Code quote:
Messages on a higher leveldoc/libpmemobj/pmemobj_log_set_threshold.3.md line 65 at r2 (raw file):
the logging function (please see **log_get_threshold**(3)). The logging function may or may not take this threshold into consideration. The default value is **PMEMOBJ_LOG_LEVEL_HARK**.
Shall we talk about "level value" or just about "level"?
Suggestion:
leveldoc/libpmemobj/pmemobj_log_set_threshold.3.md line 65 at r2 (raw file):
the logging function (please see **log_get_threshold**(3)). The logging function may or may not take this threshold into consideration. The default value is **PMEMOBJ_LOG_LEVEL_HARK**.
Shall we document only pmeobj_log_default_function() behavior in the context of the auxiliary threshold?
Code quote:
- **PMEMOBJ_LOG_THRESHOLD_AUX** - the auxiliary threshold intended for use inside
the logging function (please see **log_get_threshold**(3)). The logging
function may or may not take this threshold into consideration. The default
value is **PMEMOBJ_LOG_LEVEL_HARK**.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 80 at r2 (raw file):
- **PMEMOBJ_LOG_LEVEL_DEBUG** - debug info e.g. write operation dump THE DEFAULT LOGGING FUNCTION
Shall we have this as a separate section?
Suggestion:
# THE DEFAULT LOGGING FUNCTION #
There was a problem hiding this comment.
Reviewable status: all files reviewed, 55 unresolved discussions (waiting on @grom72 and @osalyk)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 48 at r2 (raw file):
This is how it looks right now:
ERRORS
pmemobj_log_get_threshold() can fail with the following errors: - EINVAL - threshold is not CORE_LOG_THRESHOLD nor
CORE_LOG_THRESHOLD_AUX - EINVAL - *level is NULL
You have to put a new line before the list to work properly.
Suggestion:
**pmemobj_log_get_threshold**() can fail with the following errors:
- EINVAL - threshold is not **CORE_LOG_THRESHOLD** nor **CORE_LOG_THRESHOLD_AUX**
- EINVAL - *level is NULLdoc/libpmemobj/pmemobj_log_set_function.3.md line 52 at r2 (raw file):
Parameters of a user-defined log function are as follow: - **level** - the log level of the message (see **pmemobj_log_set_threshold**(3))
Suggestion:
The parameters of a user-defined log function are as follows:
- **level** - the log level of the message (see **pmemobj_log_set_threshold**(3))doc/libpmemobj/pmemobj_log_set_function.3.md line 64 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
The default function is NULL ;)
@janekmi, please correct me if I'm wrong.
The PMEMOBJ_LOG_USE_DEFAULT_FUNCTION == NULL but it means the logging system will use the default function.
doc/libpmemobj/pmemobj_log_set_function.3.md line 73 at r2 (raw file):
# ERRORS # - EAGAIN - a temporary error occurred, the retry may fix the problem
Suggestion:
**pmemobj_log_set_function**() can set the following errno values on fail:
- EAGAIN - a temporary error occurred, the retry may fix the problemdoc/libpmemobj/pmemobj_log_set_threshold.3.md line 27 at r2 (raw file):
**pmemobj_log_set_threshold** - set the logging threshold level # SYNOPSIS #
Suggestion:
# SYNOPSIS #doc/libpmemobj/pmemobj_log_set_threshold.3.md line 57 at r2 (raw file):
Available thresholds are: - **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired
Suggestion:
Available thresholds are:
- **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesireddoc/libpmemobj/pmemobj_log_set_threshold.3.md line 68 at r2 (raw file):
Available threshold levels are defined by enum log_level: - **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info
Suggestion:
Available threshold levels are defined by enum log_level:
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library infodoc/libpmemobj/pmemobj_log_set_threshold.3.md line 94 at r2 (raw file):
**pmemobj_log_set_threshold**() can set the following errno values on fail: - EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor
Suggestion:
**pmemobj_log_set_threshold**() can set the following errno values on fail:
- EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor
There was a problem hiding this comment.
Reviewable status: all files reviewed, 55 unresolved discussions (waiting on @janekmi and @osalyk)
doc/libpmemobj/pmemobj_log_set_function.3.md line 64 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
The
PMEMOBJ_LOG_USE_DEFAULT_FUNCTION == NULLbut it means the logging system will use the default function.
I mean the default function is "0" means no default function.
There is nothing like "default" value in C especially when we talk about function parameters..
There was a problem hiding this comment.
Reviewable status: all files reviewed, 55 unresolved discussions (waiting on @grom72 and @osalyk)
a discussion (no related file):
Previously, grom72 (Tomasz Gromadzki) wrote…
@janekmi do we need
PMEMOBJ_LOG_THRESHOLD_MAXat all?
It might be useful for testing I guess. I can't imagine more uses.
There was a problem hiding this comment.
Reviewable status: 3 of 6 files reviewed, 55 unresolved discussions (waiting on @grom72 and @janekmi)
a discussion (no related file):
Previously, janekmi (Jan Michalski) wrote…
It seems you are using spaces and tabs interchangeably. Please verify what is the most common in other files and apply consistently at least in these new files.
Done.
a discussion (no related file):
Previously, grom72 (Tomasz Gromadzki) wrote…
I think we should have a common file for
core_log_get/set_tresholdas it is done forpmemobj_ctl_get/set
See how long this file is.
I have provided links to pmemobj_log_set_threshold()
a discussion (no related file):
Previously, janekmi (Jan Michalski) wrote…
It might be useful for testing I guess. I can't imagine more uses.
Done.
doc/libpmemobj/.gitignore line 10 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
Threshold documentation for get/set operations shall be in the
pmemobj_log_set_threshold.md
pmemobj_log_get_threshold.3should have the following content:.so pmemobj_log_set_threshold.3
.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 30 at r2 (raw file):
```c int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 31 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
Sorry, didn't notice the missing asterisk when reading for the first time.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 36 at r2 (raw file):
# DESCRIPTION # **pmemobj_log_get_threshold**() gets the current level of the threshold.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 42 at r2 (raw file):
**pmemobj_log_get_threshold**() function returns 0 on success or returns a non-zero value and sets errno on failure.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 47 at r2 (raw file):
**pmemobj_log_get_threshold**() can fail with the following errors: - EINVAL - threshold is not **CORE_LOG_THRESHOLD** nor **CORE_LOG_THRESHOLD_AUX**
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 48 at r2 (raw file):
**pmemobj_log_get_threshold**() can fail with the following errors: - EINVAL - threshold is not **CORE_LOG_THRESHOLD** nor **CORE_LOG_THRESHOLD_AUX** - EINVAL - *level is NULL
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 48 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
This is how it looks right now:
ERRORS
pmemobj_log_get_threshold() can fail with the following errors: - EINVAL - threshold is not CORE_LOG_THRESHOLD nor
CORE_LOG_THRESHOLD_AUX - EINVAL - *level is NULLYou have to put a new line before the list to work properly.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 19 at r2 (raw file):
[SYNOPSIS](#synopsis)<br /> [DESCRIPTION](#description)<br /> [RETURN VALUE](#return-value)<br />
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 31 at r2 (raw file):
```c #include <libpmemobj.h>
why?
doc/libpmemobj/pmemobj_log_set_function.3.md line 39 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
There is a bug in the
typedef void pmemobj_log_functionATM. In the end, it should match thetypedef void core_log_function.FYI @grom72
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 47 at r2 (raw file):
**pmemobj_log_set_function**() allows choosing the function which will get all the generated logging messages. The log_function can be either
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 52 at r2 (raw file):
Parameters of a user-defined log function are as follow: - **level** - the log level of the message (see **pmemobj_log_set_threshold**(3))
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 52 at r2 (raw file):
Parameters of a user-defined log function are as follow: - **level** - the log level of the message (see **pmemobj_log_set_threshold**(3))
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 55 at r2 (raw file):
- **file_name** - name of the source file where the message coming from. It could be set to NULL and in such case neither line_no nor function_name are provided.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 57 at r2 (raw file):
in such case neither line_no nor function_name are provided. - **line_no** - the source file line where the message coming from - **function_name** - the function name where the message coming from
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 59 at r2 (raw file):
- **function_name** - the function name where the message coming from - **message_format** - **printf**(3)-like format string of the message - "..." - additional arguments of the message format string
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 61 at r2 (raw file):
- "..." - additional arguments of the message format string THE DEFAULT LOGGING FUNCTION
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 62 at r2 (raw file):
THE DEFAULT LOGGING FUNCTION The initial value of the logging function is **CORE_LOG_USE_DEFAULT_FUNCTION**.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 69 at r2 (raw file):
**pmemobj_log_set_function**() function returns 0 on success or returns a non-zero value and sets errno on failure.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 73 at r2 (raw file):
# ERRORS # - EAGAIN - a temporary error occurred, the retry may fix the problem
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 73 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
Please apply as explained in case of the
pmemobj_log_set_threshold()and theEAGAINerror.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 77 at r2 (raw file):
# NOTE # The logging messages on the levels above the CORE_LOG_THRESHOLD level won't
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 81 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
The library will call user defined function before returning from pmemobj_log_set_function() to deliver basic information about the library:
"src version: 2.y.z" "compiled with support for shutdown state" "compiled with libndctl 63+"
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 27 at r2 (raw file):
**pmemobj_log_set_threshold** - set the logging threshold level # SYNOPSIS #
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 30 at r2 (raw file):
```c #include <libpmemobj.h>
.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 35 at r2 (raw file):
enum pmemobj_log_level level); enum log_level {
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r2 (raw file):
}; enum log_threshold {
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 49 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
Since it is a C snippet I would prefer to keep types before the function referring to them, so:
- enum pmemobj_log_level
- enum pmemobj_log_threshold
- pmemobj_log_set_threshold()
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 57 at r2 (raw file):
Available thresholds are: - **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 60 at r2 (raw file):
logging messages. Messages on a higher level than the primary threshold level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress logging.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 61 at r2 (raw file):
level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress logging. The default value is **PMEMOBJ_LOG_WARNING**.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 63 at r2 (raw file):
The default value is **PMEMOBJ_LOG_WARNING**. - **PMEMOBJ_LOG_THRESHOLD_AUX** - the auxiliary threshold intended for use inside the logging function (please see **log_get_threshold**(3)). The logging
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 65 at r2 (raw file):
the logging function (please see **log_get_threshold**(3)). The logging function may or may not take this threshold into consideration. The default value is **PMEMOBJ_LOG_LEVEL_HARK**.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 65 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
Shall we talk about "level value" or just about "level"?
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 67 at r2 (raw file):
value is **PMEMOBJ_LOG_LEVEL_HARK**. Available threshold levels are defined by enum log_level:
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 68 at r2 (raw file):
Available threshold levels are defined by enum log_level: - **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 68 at r2 (raw file):
Available threshold levels are defined by enum log_level: - **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 70 at r2 (raw file):
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info - **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the library to stop working immediately
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 72 at r2 (raw file):
immediately - **PMEMOBJ_LOG_LEVEL_ERROR** - an error that causes the library to stop working properly
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 74 at r2 (raw file):
properly - **PMEMOBJ_LOG_LEVEL_WARNING** - an error that could be handled in the upper level
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 80 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
Shall we have this as a separate section?
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 84 at r2 (raw file):
where **syslog**(3) is the primary destination (**PMEMOBJ_LOG_THRESHOLD** applies) whereas **stderr**(3) is the secondary destination (**PMEMOBJ_LOG_THRESHOLD_AUX** applies).
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 89 at r2 (raw file):
**pmemobj_log_set_threshold**() function returns 0 on success or returns a non-zero value and sets errno on failure.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 94 at r2 (raw file):
**pmemobj_log_set_threshold**() can set the following errno values on fail: - EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 96 at r2 (raw file):
- EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX** - EINVAL - level is not a value defined by enum log_level type
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 97 at r2 (raw file):
**PMEMOBJ_LOG_THRESHOLD_AUX** - EINVAL - level is not a value defined by enum log_level type - EAGAIN - a temporary error occurred, the retry may fix the problem
Done.
src/include/libpmemobj/log.h line 61 at r2 (raw file):
*/ int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
I would leave this brief description here
src/include/libpmemobj/log.h line 84 at r2 (raw file):
/* * pmemobj_log_set_function - set the logging function */
.
osalyk
force-pushed
the
logging_doc
branch
3 times, most recently
from
582e379
to
cf35dc3
Compare
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #6043 +/- ##
=======================================
Coverage 70.07% 70.07%
=======================================
Files 133 133
Lines 19563 19563
Branches 3261 3261
=======================================
+ Hits 13708 13709 +1
+ Misses 5855 5854 -1 |
There was a problem hiding this comment.
Reviewable status: 3 of 6 files reviewed, 55 unresolved discussions (waiting on @grom72 and @janekmi)
doc/libpmemobj/pmemobj_log_set_function.3.md line 64 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
I mean the default function is "0" means no default function.
There is nothing like "default" value inCespecially when we talk about function parameters..
Done.
There was a problem hiding this comment.
Reviewed 3 of 3 files at r3, 3 of 3 files at r4, all commit messages.
Reviewable status: all files reviewed, 38 unresolved discussions (waiting on @grom72 and @osalyk)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 30 at r2 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
Done.
Nope.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 14 at r4 (raw file):
[comment]: <> (Copyright 2024, Intel Corporation) [comment]: <> (pmemobj_log_get_threshold.3 -- get the logging threshold level)
Suggestion:
get the logging threshold valuedoc/libpmemobj/pmemobj_log_get_threshold.3.md line 25 at r4 (raw file):
# NAME # **pmemobj_log_get_threshold** - get the logging threshold level
Suggestion:
get the logging threshold valuedoc/libpmemobj/pmemobj_log_get_threshold.3.md line 33 at r4 (raw file):
int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
Suggestion:
enum pmemobj_log_level *valuedoc/libpmemobj/pmemobj_log_get_threshold.3.md line 39 at r4 (raw file):
**pmemobj_log_get_threshold**() gets the current *level* of the *threshold*. See **pmemobj_log_set_threshold**(3) for available thresholds and levels.
Suggestion:
**pmemobj_log_get_threshold**() gets the current *value* of the *threshold*.
See **pmemobj_log_set_threshold**(3) for available thresholds and values.doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r4 (raw file):
**pmemobj_log_get_threshold**() function returns 0 and sets the *level* value on success. On failure, it returns a non-zero value and sets errno. In case of failure, the *level* value is undefined.
Suggestion:
**pmemobj_log_get_threshold**() function returns 0 and sets the *threshold* value
on success. On failure, it returns a non-zero value and sets errno.
In case of failure, the *threshold* value is undefined.doc/libpmemobj/pmemobj_log_get_threshold.3.md line 52 at r4 (raw file):
- EINVAL - *threshold* is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX** *level* is NULL
I believe it has been removed by mistake.
Suggestion:
- EINVAL - *value* is NULLdoc/libpmemobj/pmemobj_log_set_function.3.md line 31 at r2 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
why?
The question is why it is not indented when the rest is. IMHO now it looks odd:
SYNOPSIS
#include <libpmemobj.h>
int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level *level);
doc/libpmemobj/pmemobj_log_set_function.3.md line 55 at r2 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
Done.
Not yet.
doc/libpmemobj/pmemobj_log_set_function.3.md line 52 at r3 (raw file):
The parameters of a user-defined log function are as follows: - *level* - the log level of the message (see **pmemobj_log_set_threshold**(3))
Suggestion:
The parameters of a user-defined log function are as follows:
- *level* - the log level of the message (see **pmemobj_log_set_threshold**(3))doc/libpmemobj/pmemobj_log_set_function.3.md line 76 at r3 (raw file):
**pmemobj_log_set_function**() can set the following errno values on fail: - EAGAIN - multiple threads attempted to change the *threshold* value concurrently.
Suggestion:
- EAGAIN - multiple threads attempted to change the logging function concurrently.doc/libpmemobj/pmemobj_log_set_function.3.md line 66 at r4 (raw file):
destination). This function is enabled during library initialization and can be restored using **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** value of log_function* argument.
Suggestion:
be restored using **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** value as the *log_function*
argument.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 30 at r2 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
.
.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 65 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
Shall we document only
pmeobj_log_default_function()behavior in the context of the auxiliary threshold?
I believe no. We may mention it affects the default function behaviour and refer to the default function documentation.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r3 (raw file):
PMEMOBJ_LOG_THRESHOLD, PMEMOBJ_LOG_THRESHOLD_AUX, PMEMOBJ_LOG_THRESHOLD_MAX
Suggestion:
enum pmemobj_log_threshold {
PMEMOBJ_LOG_THRESHOLD,
PMEMOBJ_LOG_THRESHOLD_AUX,
PMEMOBJ_LOG_THRESHOLD_MAX,
};doc/libpmemobj/pmemobj_log_set_threshold.3.md line 49 at r3 (raw file):
int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level level); };
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 68 at r3 (raw file):
logging function may or may not take this threshold into consideration depending on the developer's needs. For the default logging function behaviour please see **pmemobj_set_log_function**(3). The default level of this threshold is
Suggestion:
pmemobj_log_set_functiondoc/libpmemobj/pmemobj_log_set_threshold.3.md line 76 at r3 (raw file):
a few messages when the program is started and whenever a new logging function is set. Please see **pmemobj_log_set_function**(3). - **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the library to stop working
Suggestion:
programdoc/libpmemobj/pmemobj_log_set_threshold.3.md line 79 at r3 (raw file):
immediately. Sorry. - **PMEMOBJ_LOG_LEVEL_ERROR** - an error that causes the current operation or transaction to fail - **PMEMOBJ_LOG_LEVEL_WARNING** - an unexpected situation that does NOT
Suggestion:
**PMEMOBJ_LOG_LEVEL_WARNING** - an unexpected situation that does NOTdoc/libpmemobj/pmemobj_log_set_threshold.3.md line 14 at r4 (raw file):
[comment]: <> (Copyright 2024, Intel Corporation) [comment]: <> (pmemobj_log_set_threshold.3 -- set the logging threshold level)
Suggestion:
set the logging threshold valuedoc/libpmemobj/pmemobj_log_set_threshold.3.md line 25 at r4 (raw file):
# NAME # **pmemobj_log_set_threshold** - set the logging threshold level
Suggestion:
set the logging threshold valuedoc/libpmemobj/pmemobj_log_set_threshold.3.md line 54 at r4 (raw file):
# DESCRIPTION # **pmemobj_log_set_threshold**() sets the logging threshold level.
Suggestion:
**pmemobj_log_set_threshold**() sets the logging threshold value.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 60 at r4 (raw file):
- **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired logging messages. Messages on a higher level than the primary threshold level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress
Suggestion:
value are ignored.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 63 at r4 (raw file):
logging except for the basic library info. Please see the **PMEMOBJ_LOG_LEVEL_HARK** for details. The default level is **PMEMOBJ_LOG_WARNING**.
Suggestion:
The default value is **PMEMOBJ_LOG_WARNING**.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 69 at r4 (raw file):
on the developer's needs. For the default logging function behaviour please see **pmemobj_set_log_function**(3). The initial level of this threshold is **PMEMOBJ_LOG_LEVEL_HARK**.
Suggestion:
**pmemobj_set_log_function**(3). The initial value of this threshold is
**PMEMOBJ_LOG_LEVEL_HARK**.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 71 at r4 (raw file):
**PMEMOBJ_LOG_LEVEL_HARK**. Available threshold levels are defined by enum *pmemobj_log_level*:
Suggestion:
Available threshold values are defined by enum *pmemobj_log_level*:doc/libpmemobj/pmemobj_log_set_threshold.3.md line 95 at r4 (raw file):
**pmemobj_log_set_threshold**() can set the following errno values on fail: - EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor
Suggestion:
- EINVAL - *threshold* is not **PMEMOBJ_LOG_THRESHOLD** nordoc/libpmemobj/pmemobj_log_set_threshold.3.md line 97 at r4 (raw file):
- EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX** - EINVAL - level is not a value defined by enum *pmemobj_log_level* type
Suggestion:
*value* is not defined by enum *pmemobj_log_level* typesrc/include/libpmemobj/log.h line 55 at r4 (raw file):
*/ int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level level);
Suggestion:
/*
* pmemobj_log_set_threshold - set the logging threshold value
*/
int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level value);src/include/libpmemobj/log.h line 61 at r4 (raw file):
*/ int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
Suggestion:
/*
* pmemobj_log_get_threshold - get the logging threshold value
*/
int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level *value);
There was a problem hiding this comment.
Reviewable status: all files reviewed, 38 unresolved discussions (waiting on @grom72 and @janekmi)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 30 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
Nope.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 14 at r4 (raw file):
[comment]: <> (Copyright 2024, Intel Corporation) [comment]: <> (pmemobj_log_get_threshold.3 -- get the logging threshold level)
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 25 at r4 (raw file):
# NAME # **pmemobj_log_get_threshold** - get the logging threshold level
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 33 at r4 (raw file):
int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 39 at r4 (raw file):
**pmemobj_log_get_threshold**() gets the current *level* of the *threshold*. See **pmemobj_log_set_threshold**(3) for available thresholds and levels.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r4 (raw file):
**pmemobj_log_get_threshold**() function returns 0 and sets the *level* value on success. On failure, it returns a non-zero value and sets errno. In case of failure, the *level* value is undefined.
Done.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 52 at r4 (raw file):
Previously, janekmi (Jan Michalski) wrote…
I believe it has been removed by mistake.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 31 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
The question is why it is not indented when the rest is. IMHO now it looks odd:
SYNOPSIS #include <libpmemobj.h> int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 55 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
Not yet.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 52 at r3 (raw file):
The parameters of a user-defined log function are as follows: - *level* - the log level of the message (see **pmemobj_log_set_threshold**(3))
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 76 at r3 (raw file):
**pmemobj_log_set_function**() can set the following errno values on fail: - EAGAIN - multiple threads attempted to change the *threshold* value concurrently.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 66 at r4 (raw file):
destination). This function is enabled during library initialization and can be restored using **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** value of log_function* argument.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 30 at r2 (raw file):
Previously, janekmi (Jan Michalski) wrote…
.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r3 (raw file):
PMEMOBJ_LOG_THRESHOLD, PMEMOBJ_LOG_THRESHOLD_AUX, PMEMOBJ_LOG_THRESHOLD_MAX
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 49 at r3 (raw file):
int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level level); };
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 68 at r3 (raw file):
logging function may or may not take this threshold into consideration depending on the developer's needs. For the default logging function behaviour please see **pmemobj_set_log_function**(3). The default level of this threshold is
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 76 at r3 (raw file):
a few messages when the program is started and whenever a new logging function is set. Please see **pmemobj_log_set_function**(3). - **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the library to stop working
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 79 at r3 (raw file):
immediately. Sorry. - **PMEMOBJ_LOG_LEVEL_ERROR** - an error that causes the current operation or transaction to fail - **PMEMOBJ_LOG_LEVEL_WARNING** - an unexpected situation that does NOT
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 14 at r4 (raw file):
[comment]: <> (Copyright 2024, Intel Corporation) [comment]: <> (pmemobj_log_set_threshold.3 -- set the logging threshold level)
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 25 at r4 (raw file):
# NAME # **pmemobj_log_set_threshold** - set the logging threshold level
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 54 at r4 (raw file):
# DESCRIPTION # **pmemobj_log_set_threshold**() sets the logging threshold level.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 60 at r4 (raw file):
- **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired logging messages. Messages on a higher level than the primary threshold level are ignored. **PMEMOBJ_LOG_LEVEL_HARK** shall be used to suppress
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 63 at r4 (raw file):
logging except for the basic library info. Please see the **PMEMOBJ_LOG_LEVEL_HARK** for details. The default level is **PMEMOBJ_LOG_WARNING**.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 69 at r4 (raw file):
on the developer's needs. For the default logging function behaviour please see **pmemobj_set_log_function**(3). The initial level of this threshold is **PMEMOBJ_LOG_LEVEL_HARK**.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 71 at r4 (raw file):
**PMEMOBJ_LOG_LEVEL_HARK**. Available threshold levels are defined by enum *pmemobj_log_level*:
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 95 at r4 (raw file):
**pmemobj_log_set_threshold**() can set the following errno values on fail: - EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 97 at r4 (raw file):
- EINVAL - threshold is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX** - EINVAL - level is not a value defined by enum *pmemobj_log_level* type
Done.
src/include/libpmemobj/log.h line 55 at r4 (raw file):
*/ int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level level);
Done.
src/include/libpmemobj/log.h line 61 at r4 (raw file):
*/ int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold, enum pmemobj_log_level *level);
Done.
There was a problem hiding this comment.
Reviewed 3 of 4 files at r5, all commit messages.
Reviewable status: 5 of 6 files reviewed, 34 unresolved discussions (waiting on @janekmi and @osalyk)
a discussion (no related file):
See the alternative proposal:
af2c8e3#diff-bf895146e8236c14b227a570fcb9ecd208e33a22022ae2786187761dc6774b3a
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 56 at r5 (raw file):
# SEE ALSO # **pmemobj_log_set_function**(3), **pmemobj_log_set_threshold**(3).
First, point to the most informative manual -> pmemobj_log_set_treshold
Suggestion:
**pmemobj_log_set_treshold**(3), **pmemobj_log_set_function**(3).doc/libpmemobj/pmemobj_log_set_function.3.md line 84 at r2 (raw file):
# SEE ALSO # **pmemobj_log_get_threshold**(3), **pmemobj_log_set_threshold**(3).
First, point to the most informative manual -> pmemobj_log_set_treshold
Suggestion:
**pmemobj_log_set_threshold**(3), **pmemobj_log_get_threshold**(3).doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r3 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
Done.
@janekmi Why?!?!
It gives an impression of something uncompleted
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 39 at r5 (raw file):
PMEMOBJ_LOG_LEVEL_NOTICE, PMEMOBJ_LOG_LEVEL_INFO, PMEMOBJ_LOG_LEVEL_DEBUG,
Suggestion:
PMEMOBJ_LOG_LEVEL_DEBUGsrc/include/libpmemobj/log.h line 55 at r4 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
Done.
:(
src/include/libpmemobj/log.h line 61 at r4 (raw file):
Previously, osalyk (Oksana Sałyk) wrote…
Done.
:(
There was a problem hiding this comment.
Reviewable status: 5 of 6 files reviewed, 35 unresolved discussions (waiting on @janekmi and @osalyk)
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r5 (raw file):
PMEMOBJ_LOG_THRESHOLD, PMEMOBJ_LOG_THRESHOLD_AUX, PMEMOBJ_LOG_THRESHOLD_MAX,
Let's remove all _MAX
Suggestion:
PMEMOBJ_LOG_THRESHOLD_AUX
There was a problem hiding this comment.
Reviewable status: 5 of 6 files reviewed, 35 unresolved discussions (waiting on @janekmi and @osalyk)
src/include/libpmemobj/log.h line 61 at r4 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
:(
I do not understand why a less informative "value" is better than "level"
There was a problem hiding this comment.
Reviewed 4 of 4 files at r5, all commit messages.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on @grom72 and @osalyk)
a discussion (no related file):
Previously, grom72 (Tomasz Gromadzki) wrote…
See the alternative proposal:
af2c8e3#diff-bf895146e8236c14b227a570fcb9ecd208e33a22022ae2786187761dc6774b3a
IMHO the default logging behaviour should end up in libpmemobj.7. I don't think it is so important where it will be in the meantime.
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 56 at r5 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
First, point to the most informative manual ->
pmemobj_log_set_treshold
We tend to keep these links in the alphabetical order.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r3 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
@janekmi Why?!?!
It gives an impression of something uncompleted
I don't insist on having this comma.
src/include/libpmemobj/log.h line 61 at r4 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
I do not understand why a less informative "value" is better than "level"
My thinking was that having levels everywhere seemed a little bit confusing. But I am open for discussion.
This PR will be so hard discussed in the retrospective next week. xD
There was a problem hiding this comment.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on @osalyk)
doc/libpmemobj/pmemobj_log_set_function.3.md line 65 at r5 (raw file):
The library provides the default logging function which writes messages to **syslog**(3) (the primary destination) and to **stderr**(3) (the secondary destination). This function is enabled during library initialization and can
Suggestion:
**syslog**(3) and to **stderr**(3). This function is enabled during library initialization and can
There was a problem hiding this comment.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on @osalyk)
doc/libpmemobj/pmemobj_log_set_function.3.md line 67 at r5 (raw file):
destination). This function is enabled during library initialization and can be restored using **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** value as the *log_function* argument.
One more paragraph to be added:
Suggestion:
argument.
**PMEMOBJ_LOG_THRESHOLD** threshold (see **pmemobj_log_set_threshold**(3)) is used to filter out
undesired logging messages for both **syslog**(3) and **stderr**(3).
**PMEMOBJ_LOG_THRESHOLD_AUX** threshold is used to filter out undesired logging messages for
**stderr**(3). Messages reported with **PMEMOBJ_LOG_LEVEL_HARK** level are never written to stderr.
There was a problem hiding this comment.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on @janekmi and @osalyk)
a discussion (no related file):
Previously, janekmi (Jan Michalski) wrote…
IMHO the default logging behaviour should end up in libpmemobj.7. I don't think it is so important where it will be in the meantime.
I have propose one paragraph and we can forget for it at least with this PR.
There was a problem hiding this comment.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on @grom72 and @janekmi)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 56 at r5 (raw file):
Previously, janekmi (Jan Michalski) wrote…
We tend to keep these links in the alphabetical order.
👍
doc/libpmemobj/pmemobj_log_set_function.3.md line 84 at r2 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
First, point to the most informative manual ->
pmemobj_log_set_treshold
.
doc/libpmemobj/pmemobj_log_set_function.3.md line 65 at r5 (raw file):
The library provides the default logging function which writes messages to **syslog**(3) (the primary destination) and to **stderr**(3) (the secondary destination). This function is enabled during library initialization and can
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r3 (raw file):
Previously, janekmi (Jan Michalski) wrote…
I don't insist on having this comma.
Done
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 39 at r5 (raw file):
PMEMOBJ_LOG_LEVEL_NOTICE, PMEMOBJ_LOG_LEVEL_INFO, PMEMOBJ_LOG_LEVEL_DEBUG,
Done
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 45 at r5 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
Let's remove all _MAX
Done.
There was a problem hiding this comment.
Reviewed 2 of 2 files at r6, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on @janekmi and @osalyk)
There was a problem hiding this comment.
Reviewed 2 of 2 files at r6, all commit messages.
Reviewable status: all files reviewed, 12 unresolved discussions (waiting on @grom72 and @osalyk)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r6 (raw file):
**pmemobj_log_get_threshold**() function returns 0 and sets the *threshold* value on success. On failure, it returns a non-zero value and sets errno. In case of failure, the *threshold* value is undefined.
Suggestion:
On success, **pmemobj_log_get_threshold**() function returns 0 and writes into
*value* the current value of the *threshold*. On failure, it returns
a non-zero value and sets errno. In case of failure, the *value* contents is undefined.doc/libpmemobj/pmemobj_log_set_function.3.md line 67 at r5 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
One more paragraph to be added:
My suggestion. Please consider this in the context of all the other comments.
The default logging function sinks all the logging messages into **syslog**(3)
unconditionally. Additionally, it sinks a logging message into **stderr**(3)
if its logging level is not less severe than indicated by
the **PMEMOBJ_LOG_THRESHOLD_AUX** threshold's value and it is not of level
**PMEMOBJ_LOG_LEVEL_HARK**.
Note that the **PMEMOBJ_LOG_THRESHOLD** threshold's value applies to
the default logging function. Please see the notes below.
doc/libpmemobj/pmemobj_log_set_function.3.md line 53 at r6 (raw file):
The parameters of a user-defined log function are as follows: - *level* - the log level of the message (see **pmemobj_log_set_threshold**(3))
Suggestion:
(see **pmemobj_log_set_threshold**(3) for available log levels)doc/libpmemobj/pmemobj_log_set_function.3.md line 54 at r6 (raw file):
- *level* - the log level of the message (see **pmemobj_log_set_threshold**(3)) - *file_name* - name of the source file where the message coming from.
Suggestion:
where the message is coming fromdoc/libpmemobj/pmemobj_log_set_function.3.md line 57 at r6 (raw file):
It could be set to NULL and in such case, neither *line_no* nor *function_name* are provided. - *line_no* - the source file line where the message coming from
Suggestion:
where the message is coming fromdoc/libpmemobj/pmemobj_log_set_function.3.md line 58 at r6 (raw file):
are provided. - *line_no* - the source file line where the message coming from - *function_name* - the function name where the message coming from
Suggestion:
where the message is coming fromdoc/libpmemobj/pmemobj_log_set_function.3.md line 85 at r6 (raw file):
The logging messages on the levels above the **PMEMOBJ_LOG_THRESHOLD** level won't trigger the logging function.
Suggestion:
The logging messages of level less severe than indicated by
the **PMEMOBJ_LOG_THRESHOLD** threshold's value won't make it to the logging function
no matter whether the logging function is the default logging function or user-provided.doc/libpmemobj/pmemobj_log_set_function.3.md line 87 at r6 (raw file):
trigger the logging function. The user defined function must be thread-safe.
Suggestion:
The user-defined function must be thread-safe.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 62 at r6 (raw file):
logging except for the basic library info. Please see the **PMEMOBJ_LOG_LEVEL_HARK** for details. The default value is **PMEMOBJ_LOG_WARNING**.
Suggestion:
- **PMEMOBJ_LOG_THRESHOLD** - the main threshold used to filter out undesired
logging messages. Messages less severe than indicated by this threshold's
value are ignored so they won't make it to the logging function
(please see **pmemobj_log_set_function**(3)).
The default value is **PMEMOBJ_LOG_WARNING**.doc/libpmemobj/pmemobj_log_set_threshold.3.md line 70 at r6 (raw file):
**PMEMOBJ_LOG_LEVEL_HARK**. Available threshold values are defined by enum *pmemobj_log_level*:
Suggestion:
Available threshold values are defined by enum *pmemobj_log_level*.
They are listed in descending order of severity:doc/libpmemobj/pmemobj_log_set_threshold.3.md line 74 at r6 (raw file):
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info. It is used just for a few messages when the program is started and whenever a new logging function is set. Please see **pmemobj_log_set_function**(3).
Suggestion:
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info. Shall be used to
effectively suppress the logging since it is used just for a few messages
when the program is started and whenever a new logging function is set.
Please see **pmemobj_log_set_function**(3).
There was a problem hiding this comment.
Reviewable status: all files reviewed, 12 unresolved discussions (waiting on @janekmi and @osalyk)
doc/libpmemobj/pmemobj_log_set_function.3.md line 67 at r5 (raw file):
Previously, janekmi (Jan Michalski) wrote…
My suggestion. Please consider this in the context of all the other comments.
The default logging function sinks all the logging messages into **syslog**(3) unconditionally. Additionally, it sinks a logging message into **stderr**(3) if its logging level is not less severe than indicated by the **PMEMOBJ_LOG_THRESHOLD_AUX** threshold's value and it is not of level **PMEMOBJ_LOG_LEVEL_HARK**. Note that the **PMEMOBJ_LOG_THRESHOLD** threshold's value applies to the default logging function. Please see the notes below.
+1
There was a problem hiding this comment.
🐐
Reviewable status: all files reviewed, 11 unresolved discussions (waiting on @janekmi and @osalyk)
There was a problem hiding this comment.
Reviewable status: 3 of 6 files reviewed, 11 unresolved discussions (waiting on @grom72 and @janekmi)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r6 (raw file):
**pmemobj_log_get_threshold**() function returns 0 and sets the *threshold* value on success. On failure, it returns a non-zero value and sets errno. In case of failure, the *threshold* value is undefined.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 67 at r5 (raw file):
Previously, grom72 (Tomasz Gromadzki) wrote…
+1
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 53 at r6 (raw file):
The parameters of a user-defined log function are as follows: - *level* - the log level of the message (see **pmemobj_log_set_threshold**(3))
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 54 at r6 (raw file):
- *level* - the log level of the message (see **pmemobj_log_set_threshold**(3)) - *file_name* - name of the source file where the message coming from.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 57 at r6 (raw file):
It could be set to NULL and in such case, neither *line_no* nor *function_name* are provided. - *line_no* - the source file line where the message coming from
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 58 at r6 (raw file):
are provided. - *line_no* - the source file line where the message coming from - *function_name* - the function name where the message coming from
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 85 at r6 (raw file):
The logging messages on the levels above the **PMEMOBJ_LOG_THRESHOLD** level won't trigger the logging function.
Done.
doc/libpmemobj/pmemobj_log_set_function.3.md line 87 at r6 (raw file):
trigger the logging function. The user defined function must be thread-safe.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 62 at r6 (raw file):
logging except for the basic library info. Please see the **PMEMOBJ_LOG_LEVEL_HARK** for details. The default value is **PMEMOBJ_LOG_WARNING**.
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 70 at r6 (raw file):
**PMEMOBJ_LOG_LEVEL_HARK**. Available threshold values are defined by enum *pmemobj_log_level*:
Done.
doc/libpmemobj/pmemobj_log_set_threshold.3.md line 74 at r6 (raw file):
- **PMEMOBJ_LOG_LEVEL_HARK** - only basic library info. It is used just for a few messages when the program is started and whenever a new logging function is set. Please see **pmemobj_log_set_function**(3).
Done.
There was a problem hiding this comment.
Reviewed 3 of 3 files at r7, all commit messages.
Reviewable status: all files reviewed, 10 unresolved discussions (waiting on @janekmi)
There was a problem hiding this comment.
Reviewed 3 of 3 files at r7, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @osalyk)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r7 (raw file):
On success, **pmemobj_log_get_threshold**() function returns 0 and writes into *value* the current value of the *threshold*. On failure, it returns a non-zero value and sets errno. In case of failure, the *value* contents is undefined
Suggestion:
In case of failure, the *value* contents is undefinedt.
There was a problem hiding this comment.
Reviewable status: 5 of 6 files reviewed, 1 unresolved discussion (waiting on @grom72 and @janekmi)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r7 (raw file):
On success, **pmemobj_log_get_threshold**() function returns 0 and writes into *value* the current value of the *threshold*. On failure, it returns a non-zero value and sets errno. In case of failure, the *value* contents is undefined
Done.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r8, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @osalyk)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r8 (raw file):
On success, **pmemobj_log_get_threshold**() function returns 0 and writes into *value* the current value of the *threshold*. On failure, it returns a non-zero value and sets errno. In case of failure, the *value* contents is undefinedt.
Suggestion:
In case of failure, the *value* contents is undefined.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r9, all commit messages.
Reviewable status:complete! all files reviewed, all discussions resolved (waiting on @osalyk)
doc/libpmemobj/pmemobj_log_get_threshold.3.md line 45 at r8 (raw file):
On success, **pmemobj_log_get_threshold**() function returns 0 and writes into *value* the current value of the *threshold*. On failure, it returns a non-zero value and sets errno. In case of failure, the *value* contents is undefinedt.
Done.
This change is