NAME

SDL2::assert - SDL Assertion Functions

SYNOPSIS

    use SDL2::FFI qw[:assert];
        SDL_assert( 1 == 1 );
        my $test = 'nope';
        SDL_assert(
        sub {
            warn 'testing';
            my $retval = $test eq "blah";
            $test = "blah";
            $retval;
        }
    );

DESCRIPTION

SDL2::assert implements an assertion system. Failures even cause the perl debugger to halt if enabled.

Functions

These may be imported by name or with the :assert tag.

SDL_ReportAssertion( ... )

Never call this directly. Use SDL_assert( ... ), SDL_assert_release( ... ), SDL_assert_paranoid( ... ), and SDL_assert_always( ... ).

SDL_SetAssertionHandler( ... )

Set an application-defined assertion handler.

        SDL_SetAssertionHandler( sub { ... } );

This function allows an application to show its own assertion UI and/or force the response to an assertion failure. If the application doesn't provide this, SDL will try to do the right thing, popping up a system-specific GUI dialog, and probably minimizing any fullscreen windows.

This callback may fire from any thread, but it runs wrapped in a mutex, so it will only fire from one thread at a time.

This callback is NOT reset to SDL's internal handler upon SDL_Quit( )!

Expected parameters include:

handler - the SDL_AssertionHandler function to call when an assertion fails or undef for the default handler

SDL_GetDefaultAssertionHandler( )

Get the default assertion handler.

This returns the function pointer that is called by default when an assertion is triggered. This is an internal function provided by SDL, that is used for assertions when SDL_SetAssertionHandler( ... ) hasn't been used to provide a different function.

Returns the default SDL_AssertionHandler that is called when an assert triggers.

SDL_GetAssertionHandler( ... )

Get the current assertion handler.

This returns the function pointer that is called when an assertion is triggered. This is either the value last passed to SDL_SetAssertionHandler( ... ), or if no application-specified function is set, is equivalent to calling SDL_GetDefaultAssertionHandler( ).

The parameter puserdata is a pointer to a void*, which will store the "userdata" pointer that was passed to SDL_SetAssertionHandler( ... ). This value will always be NULL for the default handler. If you don't care about this data, it is safe to pass a NULL pointer to this function to ignore it.

Expected parameters include:

puserdata pointer which is filled with the "userdata" pointer that was passed to SDL_SetAssertionHandler( ... )

Returns the SDL_AssertionHandler that is called when an assert triggers.

SDL_GetAssertionReport( )

Get a list of all assertion failures.

This function gets all assertions triggered since the last call to SDL_ResetAssertionReport( ), or the start of the program.

The proper way to examine this data looks something like this:

    my $item = SDL_GetAssertionReport();
    while ($item) {
        printf( " ==> '%s', %s (%s:%d), triggered %u times, always ignore: %s.\n\n",
            $item->condition,     $item->function, $item->filename, $item->linenum,
            $item->trigger_count, $item->always_ignore ? 'yes' : 'no' );
        $item = $item->next;
    }

Returns a list of all failed assertions or NULL if the list is empty. This memory should not be modified or freed by the application.

SDL_ResetAssertionReport( )

Clear the list of all assertion failures.

        SDL_ResetAssertionReport( );

This function will clear the list of all assertions triggered up to that point. Immediately following this call, SDL_GetAssertionReport( ) will return no items. In addition, any previously-triggered assertions will be reset to a trigger_count of zero, and their always_ignore state will be false.

SDL_assert( ... )

Use this macro to create an assertion for debugging.

        SDL_assert(1 == 0);  # triggers an assertion.
        SDL_assert(1 == 1);  # does NOT trigger an assertion

This function is enabled only when the SDL_ASSERT_LEVEL is set to 2 or 3, otherwise it is disabled.

Expected parameters include:

condition - the expression to check

SDL_assert_release( ... )

Use this function to create an assertion for release builds.

        SDL_assert_release( time > -f __FILE__ );

Expected parameters include:

condition - the expression to check

This function is enabled by default. It can be disabled by setting the SDL_ASSERT_LEVEL to 0.

SDL_assert_paranoid( ... )

Use this function to create an assertion for detailed checking.

        SDL_assert_paranoid( 5 == 10 );

This function is disabled by default. It is available for use only when the SDL_ASSERT_LEVEL is set to 3.

Expected parameters include:

condition - the expression to check

SDL_assert_always( ... )

Use this function to create an assertion regardless of the current SDL_ASSERT_LEVEL.

        SDL_assert_always( 5 == 10 );

Expected parameters include:

condition - the expression to check

Types

SDL_AssertionHandler

A callback that fires when an SDL assertion fails.

This function should expect the following parameters:

data - a pointer to the SDL2::AssertData structure corresponding to the current assertion

userdata - what was passed as userdata to SDL_SetAssertionHandler( )

You should return an assert state value indicating how to handle the failure.

Defines and Enum

Defines and Enumerations listed here may be imported from SDL2::FFI with the following tags:

:assertState

SDL_ASSERTION_RETRY - Retry the assert immediately

SDL_ASSERTION_BREAK - Make the debugger trigger a breakpoint

SDL_ASSERTION_ABORT - Terminate the program

SDL_ASSERTION_IGNORE - Ignore the assert

SDL_ASSERTION_ALWAYS_IGNORE - Ignore the assert from now on

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>

cpanm SDL2::FFI

perl -MCPAN -e shell
install SDL2::FFI