PtAppAddWorkProc()

Add a WorkProc (background) function

Synopsis:

PtWorkProcId_t *PtAppAddWorkProc(
                   PtAppContext_t app_context,
                   PtWorkProc_t work_func,
                   void *data );

Library:

ph

Description:

This function adds a WorkProc entry to the WorkProc (background) process stack. The entry becomes the current WorkProc entry.

---

WorkProc functions don't run concurrently; only the one at the top of the stack runs. There is one exception to this rule. If the work procedure that's at the top of the stack is running already, the next one is called. This is only possible if the already running procedure allows the Photon library to start another one, perhaps by calling a modal function like PtModalBlock(), PtFileSelection() or PtAlert(), or calling PtLeave() while you have other threads ready to process events.

---

When there are no events pending from Photon, the current WorkProc entry's function is invoked by PtMainLoop().

The app_context argument is the address of the application context, a structure that manages all the data associated with this application. This must be specified as NULL, so that the default context is used.

The work_func argument points to the WorkProc function to be invoked when no Photon events are pending. The function takes this form:

int (*work_func)(void *data)

You can declare the function to be of type PtWorkProcF_t to take advantage of the compiler's type-checking.

---

If the WorkProc function changes the display, it should call PtFlush() to make sure the display is updated. If the WorkProc function pointed to by work_func returns Pt_CONTINUE, it stays on the WorkProc stack. If it returns Pt_END, it's removed from the WorkProc stack and the next WorkProc entry on the stack becomes the current entry.

---

Returns:

A pointer to a PtWorkProcId_t structure that identifies the specified WorkProc entry for the given application context. If an error occurs, the function returns NULL.

Examples:

This example comes from the Rebound demo. These are the callbacks that start and stop the rebounding work procedure, rebound_process().

// From src/start_rebound.c
int
start_rebound( PtWidget_t *widget, void *data,
               PtCallbackInfo_t *cbinfo )
{
  PtArg_t args[2];

  if(stopped) {
    if ( delay_value == 0 ) {
      if ( !bkgd_id ) // is one running?
        bkgd_id = PtAppAddWorkProc( NULL, rebound_process,
                                    ABW_rb_pane );
      PtSetArg( &args[0], Pt_ARG_TIMER_INITIAL, 0, 0 );
      PtSetResources( ABW_timer_wgt, 1, args );
    } else {
      if ( bkgd_id )
        PtAppRemoveWorkProc( NULL, bkgd_id );
      PtSetArg( &args[0], Pt_ARG_TIMER_INITIAL, 1, 0 );
      PtSetArg( &args[1], Pt_ARG_TIMER_REPEAT,
                SPEED_MULTIPLY*delay_value, 0 );
      PtSetResources( ABW_timer_wgt, 2, args );
    }
    stopped = 0;
  }

  return( Pt_CONTINUE );
}

// From src/stop_rebound.c
int
stop_rebound( PtWidget_t *widget, void *data,
              PtCallbackInfo_t *cbinfo )
{
  PtArg_t args[1];

  if ( bkgd_id ) {
    PtAppRemoveWorkProc( NULL, bkgd_id );
    bkgd_id = NULL;
  }
  PtSetArg( &args[0], Pt_ARG_TIMER_INITIAL, 0, 0 );
  PtSetResources( ABW_timer_wgt, 1, args );

  stopped = 1;

  return( Pt_CONTINUE );
}

Classification:

Photon

See also:

PtMainLoop(), PtAppRemoveWorkProc(), PtSetParentWidget(), PtWorkProcF_t

Parallel Operations in the Photon Programmer's Guide