PhEventRead()

Provide asynchronous event notification

Synopsis:

int PhEventRead( pid_t pid,
                 void *buffer,
                 unsigned size );

Description:

This function provides an asynchronous event-notification mechanism. You'll find it useful for applications that need to interact with Photon but also need to collect proxies or messages from other processes.

Typically, this function is called with the pid returned by Receive() to see if the message received was a proxy triggered by Photon.

If pid is the application's event proxy, PhEventRead() retrieves the event and rearms Photon. Otherwise, it returns 0. (The event proxy was attached automatically by a previous call to PhAttach().)

Photon may close a region (for example, via the window manager) before you read the pending event. As a result, PhEventRead() may indicate that no event is pending even though you were notified otherwise. In this case, PhEventRead() returns -1 and sets errno to ENOMSG.

You must call PhAttach() and PhEventArm() before the first call to this function.

Returns:

Ph_EVENT_MSG

Successful completion.

Ph_RESIZE_MSG

The Ph_DYNAMIC_BUFFER flag was set in PhAttach(), and there's a pending Photon event that's larger than the client's event buffer. This event that indicates how large the client's buffer needs to be to receive the entire event message.

0

No message was available.

-1

An error occurred.

Examples:

#define EVENT_SIZE    sizeof( PhEvent_t ) + 1000

main( int argc, char *argv[] )
{
     pid_t pid;
     PhEvent_t *event;
     struct app_msg msg;

     if( initialize() == -1 )
         exit( EXIT_FAILURE );

     if( NULL == ( event = malloc( EVENT_SIZE ) ) )
          exit( EXIT_FAILURE );
     PhEventArm();

     while( 1 ) {
          pid = Receive( 0, &msg, sizeof( msg ) );
          switch( PhEventRead( pid, event, EVENT_SIZE ) ) {
               case Ph_EVENT_MSG:
                  PtEventHandler( event );
                  break;
               case 0:
                  process_app_msg( &msg );
                  break;
              case -1:
                  perror( "PhEventRead failed" );
                  break;
          }
     }
}

Classification:

Photon

See also:

PhAttach(), PhEventArm(), PhEventNext(), PhEventPeek()

Receive() in the C Library Reference.