PtLeave()

Unlock the Photon library for use by other threads

Synopsis:

int PtLeave( int flags );

Description:

This function is the opposite to PtEnter(); it "unlocks" the library and lets other threads use Photon functions.

Don't call PtLeave() if your thread hasn't locked the library by successfully calling PtEnter(). If you do, your application will crash if you're lucky, or just randomly corrupt some data if you're less lucky.

PtLeave() doesn't atomically give the library lock to another thread blocked inside PtEnter(); the other thread gets unblocked, but then it must compete with any other threads as if it just called PtEnter().

The value of flags can be one of:

Pt_EVENT_PROCESS_ALLOW: Turn the calling thread into an event reader.
Pt_EVENT_PROCESS_PREVENT: Turn the calling thread into a nonreader.

In most cases, it's better to set neither of these bits in flags, in which case the thread's status as event reader or nonreader doesn't change.

You can OR the following into the flags:

Pt_DELAY_EXIT: Prevent another thread from terminating this one by calling PtExit().

Returns:

0: Success. and the state of the thread didn't change.
> 0: Success, and the state of the thread changed. You can pass this value to PtEnter() to restore the previous state of the thread
< 0: An error occurred; the value is a negative error code.

Examples:

int flags;
if ( ( flags = PtLeave( Pt_EVENT_PROCESS_PREVENT ) ) < 0 )
    fprintf( stderr, "Couldn't leave: %s\n",
             strerror( -flags ) );
else {
    do_some_lengthy_stuff();
    /* This will turn your thread back into a reader if it
       was a reader  before: */
    if ( ( flags = PtEnter( flags ) ) < 0 )
        fprintf( stderr, "Couldn't enter: %s\n",
                 strerror( -flags ) );
    }

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes