PtEnter()

Lock the Photon library for use by a single thread

Synopsis:

int PtEnter( int flags );

Description:

This function gives the calling thread access to the Photon library by "locking the library." If another thread has already locked the library, PtEnter() blocks until the library is unlocked.

Since Photon functions aren't thread-safe, any thread other than the one that called PtInit() must call PtEnter() before trying to call any other Photon functions. After you're done, call PtLeave() to give other threads access to the library.

PtProcessEvent() unlocks the library before waiting for an event, and locks it back after. If you're calling PtProcessEvent() or any other function that processes Photon events (like PtBkgdHandlerProcess() or PtModalBlock()), other threads may enter and leave the library while you're waiting for an event. The same applies to PtCondWait() and PtCondTimedWait(), even though these functions don't process Photon events.

Mixing threads and work procedures might cause a minor problem; if one of the other threads adds a workproc while another thread is already waiting for an event, the workproc might not be invoked until you receive an event.

As with other Pt functions, you have to make sure that PtInit() has been called (and succeeded) before you can call PtEnter().

The lock implemented by PtEnter() and PtLeave() isn't recursive (in the way that mutexes can be recursive). If you call PtEnter() twice without calling PtLeave() in between, the second call to PtEnter() fails and returns the negative of EDEADLK.

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 PtLeave() to restore the previous state of the thread
< 0: An error occurred; the value is a negative error code.

Errors:

If an error occurs, PtEnter() returns the negative of:

EDEADLK: The library is already locked by the calling thread.

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