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.

---

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:

• Pt_EVENT_PROCESS_ALLOW—The thread was a reader, and PtLeave() was called with flags set to Pt_EVENT_PROCESS_PREVENT.
• Pt_EVENT_PROCESS_PREVENT—The thread was a nonreader, and PtLeave() was called with flags set to Pt_EVENT_PROCESS_ALLOW .
• Pt_DELAY_EXIT—For both the current call to PtLeave() and the previous call to PtEnter(), flags was set to Pt_DELAY_EXIT.

  ---

  Some functions will reset the Pt_DELAY_EXIT flag bit for the thread to 0, which will affect the return value. These functions are PtCondWait(), PtCondTimedWait(), and any function that reads and processes an event (such as PtProcessEvent() or PtModalBlock()).

  ---

< 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

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