libhatchet.h File Reference

Go to the source code of this file.

Macros
#define	LIBHATCHET_VER   14903
#define	LIBHATCHET_TAG   "v1.49.3"
#define	HX_HARDENING_MODE   HX_HARDENING_MODE_DEBUG
#define	HX_HARDENING_MODE_NONE   0
#define	HX_HARDENING_MODE_STANDARD   1
#define	HX_HARDENING_MODE_VERBOSE   2
#define	HX_HARDENING_MODE_DEBUG   3
#define	hxinit()
#define	hxassert(x_)
#define	hxassertmsg(x_, ...)
#define	hxassert_hard(x_, ...)
#define	hxassert_always(x_, ...)
#define	hxlog(...)
#define	hxlog_release(...)
#define	hxlog_console(...)
#define	hxlog_warning(...)
#define	hxwarn_msg(x_, ...)
#define	hxnull   0

Typedefs
typedef ptrdiff_t	hxsize_t
typedef uint32_t	hxhash_t
typedef uint64_t	hxhandle_t

Enumerations
enum	hxlog_level_t { hxlog_level_log , hxlog_level_console , hxlog_level_warning , hxlog_level_assert }

Functions
void	hxinit_internal (int version_)
void	hxshutdown (void)
bool	hxassert_handler (const char *file_, size_t line_)
void	hxset_assert_handler (bool(*handler_)(void))
void	hxlog_handler (enum hxlog_level_t level_, const char *format_,...)
void	hxlog_handler_v (enum hxlog_level_t level_, const char *format_, va_list args_)
void	hxexit (int status_)
template<typename T>
constexpr hxsize_t	hxsizeof (void)
template<typename T>
constexpr hxsize_t	hxsizeof (T &)

Variables
constexpr hxhash_t	hxhash_bits = 32u
constexpr hxhandle_t	hxnull_handle = 0u

Detailed Description

Provides core macros, memory management and feature detection.

Requires C99 for C. C++11 is minimum for C++. Utilizes language features up to C++20. Inclusion on the compiler search path is not required. However, the headers are intended to be included as follows: #include <hx/libhatchet.h>

Defines logging macros hxlog, hxlog_release, hxlog_console, hxlog_warning which vary by HX_USE_LOGGING and defines log verbosity { log, console, warning, assert }.

Assertion macros hxassert, hxassertmsg are active only when HX_HARDENING_MODE == HX_HARDENING_MODE_DEBUG. hxassert_hard is active when HX_HARDENING_MODE != HX_HARDENING_MODE_NONE.

Macro Definition Documentation

HX_HARDENING_MODE

#define HX_HARDENING_MODE   HX_HARDENING_MODE_DEBUG

HX_HARDENING_MODE - Library hardening level. See the README.md for levels.

HX_HARDENING_MODE_DEBUG

#define HX_HARDENING_MODE_DEBUG   3

HX_HARDENING_MODE_DEBUG - Provides comprehensive asserts and verbose output.

HX_HARDENING_MODE_NONE

#define HX_HARDENING_MODE_NONE   0

HX_HARDENING_MODE_NONE - Omits library hardening and disables all asserts.

HX_HARDENING_MODE_STANDARD

#define HX_HARDENING_MODE_STANDARD   1

HX_HARDENING_MODE_STANDARD - Provides hardening but saves space by omitting verbose output.

HX_HARDENING_MODE_VERBOSE

#define HX_HARDENING_MODE_VERBOSE   2

HX_HARDENING_MODE_VERBOSE - Provides verbose messages, suitable for internal release.

hxassert

#define hxassert

(

x_

)

Value:

    (void)((bool)(x_)   /* THIS IS USED AS A COMPILE TIME ASSERT: */  \
    || (hxlog_handler_(hxlog_level_assert, #x_), hxassert_handler(__FILE__, __LINE__)) \
    || hxbreakpoint())

hxassert(bool x) - Logs an error and terminates execution if x is false.

This is only evaluated when HX_HARDENING_MODE == HX_HARDENING_MODE_DEBUG. Always evaluates to an expression of type void. May be used as a compile time assert after C++23.

• x : The condition to evaluate.

hxassert_always

#define hxassert_always	(		x_,
			... )

Value:

    (void)((bool)(x_) /* THIS IS USED AS A COMPILE TIME ASSERT: */ \
    || (hxlog_handler_(hxlog_level_assert, __VA_ARGS__), hxassert_handler(__FILE__, __LINE__))  \
    || hxbreakpoint())

hxassert_always(bool x, ...) - Logs an error and terminates execution if x is false.

This is always evaluated regardless of HX_HARDENING_MODE. Always evaluates to an expression of type void. May be used as a compile time assert after C++23.

• x : The condition to evaluate.
• ... Printf-style formatted log message.

hxassert_hard

#define hxassert_hard	(		x_,
			... )

Value:

    (void)((bool)(x_) /* THIS IS USED AS A COMPILE TIME ASSERT: */  \
    || (hxlog_handler_(hxlog_level_assert, __VA_ARGS__), hxassert_handler(__FILE__, __LINE__)) \
    || hxbreakpoint())

hxassert_hard(bool x, ...) - Logs an error and terminates execution if x is false.

This is only evaluated when HX_HARDENING_MODE != HX_HARDENING_MODE_NONE. Always evaluates to an expression of type void. May be used as a compile time assert after C++23.

• x : The condition to evaluate.
• ... Printf-style formatted log message.

hxassertmsg

#define hxassertmsg	(		x_,
			... )

Value:

    (void)((bool)(x_)    /* THIS IS USED AS A COMPILE TIME ASSERT: */ \
    || (hxlog_handler_(hxlog_level_assert, __VA_ARGS__), hxassert_handler(__FILE__, __LINE__)) \
    || hxbreakpoint())

hxassertmsg(bool x, ...) - Logs an error and terminates execution if x is false.

Does not evaluate message args unless condition fails. This is only evaluated when HX_HARDENING_MODE == HX_HARDENING_MODE_DEBUG. Always evaluates to an expression of type void. e.g., hxassertmsg(x == 0, "x: d", x). May be used as a compile time assert after C++23.

• x : The condition to evaluate.
• ... Printf-style formatted log message.

hxinit

#define hxinit

(

)

Value:

(void)(hxg_init_ver_ == LIBHATCHET_VER || (hxinit_internal(LIBHATCHET_VER), 0))

Compile-time assertion for HX_HARDENING_MODE [0..3] range.

hxinit - Initializes the platform if needed. Does a quick version check to determine if the platform is already correctly initialized first. See hxg_init_ver_. LIBHATCHET_VER is checked against the value hxinit_internal was compiled with. WARNING: Call in main(). Not thread safe.

hxlog

#define hxlog

(

...

)

Value:

hxlog_handler(hxlog_level_log, __VA_ARGS__)

hxlog(...) - Enters formatted messages in the system log.

Does not add a newline. Only evaluated if HX_USE_LOGGING is 2 or above.

• ... Printf-style formatted log message.

hxlog_console

#define hxlog_console

(

...

)

Value:

hxlog_handler(hxlog_level_console, __VA_ARGS__)

hxlog_console(...) - Enters formatted messages in the console system log.

• ... Variadic arguments for the formatted console log message.

hxlog_release

#define hxlog_release

(

...

)

Value:

hxlog_handler(hxlog_level_log, __VA_ARGS__)

hxlog_release(...) - Enters formatted messages in the system log up to release level 1.

• ... Printf-style formatted log message.

hxlog_warning

#define hxlog_warning

(

...

)

Value:

hxlog_handler(hxlog_level_warning, __VA_ARGS__)

hxlog_warning(...) - Enters formatted warnings in the system log.

• ... Variadic arguments for the formatted warning message.

hxnull

#define hxnull   0

hxnull - The null pointer value for a given pointer type represented by the numeric constant 0.

The C/C++ language standards explicitly define the meaning of 0 in pointer context as a null pointer of the expected type. However they do not define whether NULL is 0 or ((void*)0). hxnull fills that gap by having an unambiguous type. See hxnullptr/hxnullptr_t if you need a std::nullptr_t replacement.

hxwarn_msg

#define hxwarn_msg	(		x_,
			... )

Value:

    (void)((bool)(x_) \
    || (hxlog_handler(hxlog_level_warning, __VA_ARGS__), 0))

hxwarn_msg(bool x, ...) - Enters formatted warnings in the system log when x is false.

• x : The condition to evaluate.
• ... Variadic arguments for the formatted warning message.

LIBHATCHET_TAG

#define LIBHATCHET_TAG   "v1.49.3"

LIBHATCHET_TAG - Major, minor and patch version tag name.

LIBHATCHET_VER

#define LIBHATCHET_VER   14903

int LIBHATCHET_VER - One digit major, and two digit minor and patch versions.

Typedef Documentation

hxhandle_t

typedef uint64_t hxhandle_t

hxhandle_t - An opaque 64-bit handle.

hxhash_t

typedef uint32_t hxhash_t

hxhash_t - Unsigned 32-bit hash value. Expect collisions.

hxsize_t

typedef ptrdiff_t hxsize_t

hxsize_t - A signed size type, same as ssize_t or ptrdiff_t.

Use on a 32-bit system with more than 2 GiB RAM is undefined.

Enumeration Type Documentation

hxlog_level_t

enum hxlog_level_t

hxlog_level_t - Runtime setting for verbosity of log messages.

Independently controls what messages are compiled in. See hxg_settings.log_level.

Enumerator
hxlog_level_log	hxlog_level_log - Written to hxout. Structured output. No automatic newline.
hxlog_level_console	hxlog_level_console - Written to hxerr. Unstructured informative output including error messages regarding console commands and hxtest results. No automatic newline. No news is good news.
hxlog_level_warning	hxlog_level_warning - Written to hxerr. Warnings about serious problems.
hxlog_level_assert	hxlog_level_assert - Written to hxerr. Reason for abnormal termination or test failure.

Function Documentation

hxassert_handler()

bool hxassert_handler	(	const char *	file_,
		size_t	line_ )

hxassert_handler - Assert handler.

Do not call directly, signature changes and then is removed. WARNING: Compile errors from consteval code calling this function are intentional and are how you know a compile time assert has been hit.

hxexit()

void hxexit

(

int

status_

)

hxexit(int status) - Flushes hxout and hxerr then calls _Exit.

• status : The exit status passed to _Exit.

hxinit_internal()

void hxinit_internal

(

int

version_

)

hxinit_internal - Internal. Use hxinit instead. It checks hxg_init_ver_.

hxlog_handler()

void hxlog_handler	(	enum hxlog_level_t	level_,
		const char *	format_,
			... )

hxlog_handler - Enters formatted messages in the system log.

• level : The log level (e.g., hxlog_level_log, hxlog_level_warning).
• format : Non-null printf-style format string.
• ... Additional arguments that must satisfy the format string.

hxlog_handler_v()

void hxlog_handler_v	(	enum hxlog_level_t	level_,
		const char *	format_,
		va_list	args_ )

hxlog_handler_v - A va_list version of hxlog_handler.

• level : The log level (e.g., hxlog_level_log, hxlog_level_warning).
• format : Non-null printf-style format string.
• args : A va_list containing the arguments for the format string.

hxset_assert_handler()

void hxset_assert_handler

(

bool(*

handler_ )(void)

)

hxset_assert_handler - Installs a custom handler called when an assertion fails.

Pass hxnull to disable. If it returns true the assert will not exit or trigger a breakpoint.

• handler : Function pointer of type bool (*)(void), or hxnull.

hxshutdown()

void hxshutdown

(

void

)

hxshutdown - Terminates service.

Releases all resources acquired by the platform and confirms all memory allocations have been released.

hxsizeof() [1/2]

template<typename T>

hxsize_t hxsizeof ( T & )

constexpr

hxsizeof() [2/2]

template<typename T>

hxsize_t hxsizeof ( void )

constexpr

hxsizeof - Returns the size of a type or expression as hxsize_t.

Variable Documentation

hxhash_bits

hxhash_t hxhash_bits = 32u

inlineconstexpr

hxhash_bits - Number of bits in hxhash_t.

hxnull_handle

hxhandle_t hxnull_handle = 0u

inlineconstexpr

hxnull_handle - A handle that will never refer to a valid object.