Troubleshooting Windows C++ SDK

Using the PUBNUB_ASSERT subsystem

The PUBNUB_ASSERT subsystem provides a powerful debugging and troubleshooting tool for the POSIX C SDK. Assertions act as runtime verification points that help identify logic errors, invalid states, and unexpected conditions in your code.

Unlike standard C assertions, the PubNub assertion system offers configurable levels of checking, allowing developers to balance between thorough debugging capabilities and runtime performance. When an assertion fails, it immediately shows you exactly which file and line caused the error.

Proper use of assertions during development helps catch bugs early, validate assumptions, and ensure code robustness before deployment to production environments.

C-core has its own ASSERT module/subsystem. It's interface is in the header pubnub_assert.h. It is used in C-core modules themselves, but you can also use it in your code if you wish. It provides several levels of ASSERTs:

Level	Preprocessor Symbol	Description
highest	PUBNUB_ASSERT_LEVEL_EX	All checks enabled (compiled).
regular	PUBNUB_ASSERT_LEVEL	Only the long lasting checks are disabled, other are compiled.
lowest	PUBNUB_ASSERT_LEVEL_OPT	Only the checks with negligible execution length are enabled.
none	PUBNUB_ASSERT_LEVEL_NONE	All checks disabled.

The default level is regular, and that is the level used in our sample Makefiles. So, if you want the highest level for troubleshooting, define PUBNUB_ASSERT_LEVEL_EX preprocessor symbol when compiling. Also, if you want to troubleshoot performance by disabling checks, define PUBNUB_ASSERT_LEVEL_NONE.

Also, you can control what happens when an assertion fails. To do that, you set a callback function to be called, by using pubnub_assert_set_handler(), which should be called as early as possible in the execution of your program.

There are a few ready-made handlers which you can use and the default is pubnub_assert_handler_abort, which provides a similar operation as the C standard assert() macro - prints a report of the place and expression of the assertion and then aborts.

If you wish to provide your own handler, you need to define a function that conforms to the following typedef:

typedef void (*pubnub_assert_handler_t)(char const *s, char const *file, long line);

For example:

void dbg_break_assert_handler(char const *s, char const *file, long line)
    {
        printf("Will hit breakpoint for '%s' in %s line %d\n", s, file, line);
        BREAK_IN_DEBUGGER; /* assuming you have such a macro */
    }