PA_Yield

version 2003

PA_Yield

Parameter	Type		Description
This command does not require any parameters

The routine PA_Yield tells the 4D scheduler to execute one time-slice of all other running processes if one 60 th of a second has elapsed since the last scheduler execution cycle.

PA_Yield MUST be called within any 4D plug-in looping structure which is known will not give back the control to the 4D scheduler if the entry point is not called. If this is NOT done all other processes will not execute for the duration of the loop.

This is like the IDLE 4th Dimension command.

Some examples:

· A 4D Extension browses a selection of records using PA_NextRecord, or parses a document on disk, or manipulates a large amount of private data. In this case calling PA_Yield allows the execution of the other processes while processing a time-consuming operation. In this case not calling PA_Yield would give the user the feeling that the program is "frozen" because other processes would not be able to answer to the events. For obvious reasons this is not a desirable feature.

· A 4D Plug-in displays a modal dialog box using the API's Dialogs routines. A call to PA_Yield is not necessary since the dialog routines include a call to the 4D scheduler.

Because calling PA_Yield potentially allows the execution of the other processes, concurrent access to interprocess objects must be taken into account. If for example PA_Yield is called while performing a time-consuming browsing operation on an interprocess array it is possible that another process might access this array in the middle of the operation.

To handle this case two solutions can be adopted:

· Make the operation "atomic" by not calling PA_Yield.

· Document that a call to the 4D Extension routine applied to an interprocess object must be protected at the 4D Language level by a local semaphore.

The second solution is preferable. The execution of the 4D Environment is not "stopped" and the user of 4D plug-in (potentially a 4D developer) is allowed more freedom with respect to how the particular situation is handled.

(1) Browsing a selection of records. A call to PA_Yield is necessary.

   void DoSomethingWithTheSelection(short tNum)
   {
      do
      {
         PA_Yield(); // Give time to other processes
         /* . . . do something with the record . . .*/
         PA_NextRecord(tNum);
      }while(! PA_EndSelection(tNum));
   }

(2) A long internal loop:

   void ParseBigData (char *dataPtr, long dataSize)
   {
      long   i ;

      for(i = 0; i < dataSize; i++)
      {
         DoThis(*dataPtr++);
         DoThat(*dataPtr++);
         PA_Yield(); // time to breath a bit
      }
   }

PA_YieldAbsolute.

PA_GetLastError always returns eER_NoErr