Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PtLeave()

Unlock the Photon library for use by other threads

Synopsis:

int PtLeave( int flags );

Arguments:

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. For more information about changing a thread's event reader status, see Threads in the Parallel Operations chapter of the Photon Programmer's Guide.

You can OR the following into the flags:

Pt_DELAY_EXIT
Prevent another thread from terminating the process by calling PtExit().

If another thread calls PtExit() after you unlock the library, or has called PtExit() before you last called PtEnter(), the Pt_DELAY_EXIT flag ensures that the process will not exit at least until this thread terminates or calls PtEnter().

Library:

ph

Description:

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


Note: 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().

Returns:

0
Success. and the state of the thread didn't change.
> 0
Success, and the state of the thread changed. The return value can be a combination of:
< 0
An error occurred; the value is a negative error code.

Errors:

EINVAL
The parameter flags is an incorrect value.

Examples:

You can test whether you have the Photon Library locked by evaluating PtEnter(). If the Photon Library is already locked, PtEnter() will fail with an error of -EDEADLK. When PtLeave() is called with a negative value, it is guaranteed to fail, so in this example the Photon Library has the same lock state as it had before the call to PtEnter():

int eval;
if ((eval = PtEnter(0)) < 0 && eval != -EDEADLK)
  fprintf( stderr, “Couldn't enter: %s\n“,
             strerror( -eval ) );
else
{
  PtSetResource(w, Pt_ARG_WINDOW_TITLE, text, 0);
  PtLeave(eval);  // does nothing if eval == -EDEADLK
}

In this example, the Photon Library is locked elsewhere, and you want to unlock it to perform some lengthy operation, such as in a widget callback where not unlocking the library would “freeze” the GUI for the duration of the operation:

int my_callback(  PtWidget_t * widget, ApInfo_t * apinfo,
                  PtCallbackInfo_t * cbinfo )
{
  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 ) );
    }
    ...
    return( Pt_CONTINUE );
 }

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

PtEnter(), PtExit()

pthread_mutex_unlock() in the QNX Neutrino Library Reference

Threads in the Parallel Operations chapter of the Photon Programmer's Guide