Skip to content

Commit

Permalink
doc: logging function documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
osalyk committed Mar 12, 2024
1 parent b00e032 commit 582e379
Show file tree
Hide file tree
Showing 6 changed files with 261 additions and 139 deletions.
3 changes: 2 additions & 1 deletion doc/Makefile
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright 2014-2023, Intel Corporation
# Copyright 2014-2024, Intel Corporation
#

#
Expand All @@ -18,6 +18,7 @@ MANPAGES_3_MD = libpmem/pmem_flush.3.md libpmem/pmem_is_pmem.3.md libpmem/pmem_m
libpmemobj/pmemobj_list_insert.3.md libpmemobj/pmemobj_memcpy_persist.3.md libpmemobj/pmemobj_mutex_zero.3.md \
libpmemobj/pmemobj_open.3.md libpmemobj/pmemobj_root.3.md libpmemobj/pmemobj_tx_begin.3.md libpmemobj/pmemobj_tx_add_range.3.md \
libpmemobj/pmemobj_tx_alloc.3.md libpmemobj/pobj_layout_begin.3.md libpmemobj/pobj_list_head.3.md libpmemobj/toid_declare.3.md \
libpmemobj/pmemobj_log_get_threshold.3.md libpmemobj/pmemobj_log_set_function.3.md libpmemobj/pmemobj_log_set_threshold.3.md \
libpmempool/pmempool_check_init.3.md libpmempool/pmempool_feature_query.3.md libpmempool/pmempool_rm.3.md libpmempool/pmempool_sync.3.md

MANPAGES_1_MD = pmempool/pmempool.1.md pmempool/pmempool-info.1.md pmempool/pmempool-create.1.md \
Expand Down
3 changes: 3 additions & 0 deletions doc/libpmemobj/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ pmemobj_alloc.3
pmemobj_ctl_get.3
pmemobj_first.3
pmemobj_list_insert.3
pmemobj_log_get_threshold.3
pmemobj_log_set_function.3
pmemobj_log_set_threshold.3
pmemobj_memcpy_persist.3
pmemobj_mutex_zero.3
pmemobj_open.3
Expand Down
56 changes: 56 additions & 0 deletions doc/libpmemobj/pmemobj_log_get_threshold.3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
draft: false
slider_enable: true
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: ["pmemobj_log_get_threshold.3.html"]
title: "libpmemobj | PMDK"
header: "pmemobj API version 2.3"
---

[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
[comment]: <> (Copyright 2024, Intel Corporation)

[comment]: <> (pmemobj_log_get_threshold.3 -- get the logging threshold level)

[NAME](#name)<br />
[SYNOPSIS](#synopsis)<br />
[DESCRIPTION](#description)<br />
[RETURN VALUE](#return-value)<br />
[ERRORS](#errors)<br />
[SEE ALSO](#see-also)<br />

# NAME #

**pmemobj_log_get_threshold** - get the logging threshold level

# SYNOPSIS #

```c
#include <libpmemobj.h>

int pmemobj_log_get_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level *level);
```
# DESCRIPTION #
**pmemobj_log_get_threshold**() gets the current *level* of the *threshold*.
See **pmemobj_log_set_threshold**(3) for available thresholds and levels.
# RETURN VALUE #
**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.
# ERRORS #
**pmemobj_log_get_threshold**() can fail with the following errors:
- EINVAL - *threshold* is not **PMEMOBJ_LOG_THRESHOLD** nor **PMEMOBJ_LOG_THRESHOLD_AUX**
*level* is NULL
# SEE ALSO #
**pmemobj_log_set_function**(3), **pmemobj_log_set_threshold**(3).
96 changes: 96 additions & 0 deletions doc/libpmemobj/pmemobj_log_set_function.3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
draft: false
slider_enable: true
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: ["pmemobj_log_set_function.3.html"]
title: "libpmemobj | PMDK"
header: "pmemobj API version 2.3"
---

[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
[comment]: <> (Copyright 2024, Intel Corporation)

[comment]: <> (pmemobj_log_set_function.3 -- set the logging function)

[NAME](#name)<br />
[SYNOPSIS](#synopsis)<br />
[DESCRIPTION](#description)<br />
[THE DEFAULT LOGGING FUNCTION](#the-default-logging-function)<br />
[RETURN VALUE](#return-value)<br />
[ERRORS](#errors)<br />
[NOTE](#note)<br />
[SEE ALSO](#see-also)<br />

# NAME #

**pmemobj_log_set_function**() - set the logging function

# SYNOPSIS #

```c
#include <libpmemobj.h>

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);

int pmemobj_log_set_function(pmemobj_log_function *log_function);
```
# DESCRIPTION #
**pmemobj_log_set_function**() allows choosing the function which will get all
the generated logging messages. The *log_function* can be either
**PMEMOBJ_LOG_USE_DEFAULT_FUNCTION** which will use the default logging function
(built into the library) or a pointer to a user-defined function.
The parameters of a user-defined log function are as follows:
- *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. 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
- *function_name* - the function name where the message coming from
- *message* - the message string
# THE DEFAULT LOGGING FUNCTION #
The initial value of the logging function is **PMEMOBJ_LOG_USE_DEFAULT_FUNCTION**.
This function writes messages to **syslog**(3) (the primary destination) and to
**stderr**(3) (the secondary destination).
# RETURN VALUE #
**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.
# ERRORS #
**pmemobj_log_set_function**() can set the following errno values on fail:
- 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.
# NOTE #
The logging messages on the levels above the **PMEMOBJ_LOG_THRESHOLD** level won't
trigger the logging function.
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+"
# SEE ALSO #
**pmemobj_log_get_threshold**(3), **pmemobj_log_set_threshold**(3).
104 changes: 104 additions & 0 deletions doc/libpmemobj/pmemobj_log_set_threshold.3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
draft: false
slider_enable: true
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: ["pmemobj_log_set_threshold.3.html"]
title: "libpmemobj | PMDK"
header: "pmemobj API version 2.3"
---

[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
[comment]: <> (Copyright 2024, Intel Corporation)

[comment]: <> (pmemobj_log_set_threshold.3 -- set the logging threshold level)

[NAME](#name)<br />
[SYNOPSIS](#synopsis)<br />
[DESCRIPTION](#description)<br />
[RETURN VALUE](#return-value)<br />
[ERRORS](#errors)<br />
[SEE ALSO](#see-also)<br />

# NAME #

**pmemobj_log_set_threshold** - set the logging threshold level

# SYNOPSIS #

```c
#include <libpmemobj.h>

enum pmemobj_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 pmemobj_log_threshold {
PMEMOBJ_LOG_THRESHOLD,
PMEMOBJ_LOG_THRESHOLD_AUX,
PMEMOBJ_LOG_THRESHOLD_MAX

int pmemobj_log_set_threshold(enum pmemobj_log_threshold threshold,
enum pmemobj_log_level level);
};
```
# DESCRIPTION #
**pmemobj_log_set_threshold**() sets the logging threshold level.
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
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.
The default level is **PMEMOBJ_LOG_WARNING**.
- **PMEMOBJ_LOG_THRESHOLD_AUX** - the auxiliary threshold intended for use inside
the logging function (please see **pmemobj_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 level of this threshold is
**PMEMOBJ_LOG_LEVEL_HARK**.
Available threshold levels are defined by enum *pmemobj_log_level*:
- **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).
- **PMEMOBJ_LOG_LEVEL_FATAL** - an error that causes the library to stop working
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
cause the current operation to fail
- **PMEMOBJ_LOG_LEVEL_NOTICE** - non-massive info mainly related to public API
function completions
- **PMEMOBJ_LOG_LEVEL_INFO** - massive info e.g. every write operation indication
- **PMEMOBJ_LOG_LEVEL_DEBUG** - debug info e.g. write operation dump
# RETURN VALUE #
**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.
# ERRORS #
**pmemobj_log_set_threshold**() can set the following errno values on fail:
- 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
- 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.
# SEE ALSO #
**pmemobj_log_get_threshold**(3), **pmemobj_log_set_function**(3).
Loading

0 comments on commit 582e379

Please sign in to comment.