|
|
|
|
|
|
|
|
|
version 2003
An external process is a process that belongs to a plug-in, launched by the routine PA_NewProcess. The plug-in runs the process, takes care of its windows and menus, and interacts with the user if necessary. An external process can be invisible and/or can have no user interface.
4th Dimension allows the plug-in the possibility of creating this external process and then send it all events belonging to it if it has a user interface.
To create and manage an external process, the plug-in must execute the following instructions:
- Create the process, by calling PA_NewProcess, passing it a stack size, a process name, and a pointer to the routine that runs the process.
- Run the process code(see below) and interact with the user if necessary.
- Repetitively call PA_IsProcessDying to know if it must terminate
- Call PA_KillProcess when it has finished its work.
While writing an external process, the following actions MUST be performed:
· The routine of the process code has no parameters.
· At the very beginning of the code, PA_YieldAbsolute must be called. This allows the 4D scheduler to correctly handle the addition of the external process to its internal process table.
· If, as it should be, the external process includes a waiting loop :
- it must call PA_WaitNextEvent to get the current event returned (such as mouseDown). On Macintosh, it can use GetNextEvent instead, but for cross-platform purpose it is recommended to use PA_WaitNextEvent. Calling PA_WaitNextEvent is important, since this routine gives the hand to 4D for other processes. If the main loop of the external process never calls it, other processes will be frozen.
NOTE
If the external process has no user interface, the main loop can either call PA_WaitNextEvent or PA_Yield to give time for other running processes.
- it must call PA_IsProcessDying to see if the user or 4th Dimension wants the process to abort. If PA_IsProcessDying returns 1, the external process must exit the event loop as soon as possible and call PA_KillProcess.
Executing external processes receives 1 in PA_IsProcessDying when:
· The user chooses Quit, New Database, or Open Database from the 4D File menu
· The 4D command QUIT 4D is called,
· The routine PA_Quit is called.
· The user chooses "Abort" in the Runtime Explorer
The 4D scheduler takes control and tells the external processes that it must terminate. It waits for a predetermined period of time and then forcefully aborts any remaining executing processes . If the process is terminated because the database is closed, it is at this point that 4D will call the kDeInitPlugin or kServerDeInitPlugin phase of the 4D plug-in.
· Calling PA_IsProcessDying MUST be the last action performed by a terminating external process. This assures that the 4D scheduler is notified of the termination and updates its internal process table according.
· The 4D plug-in should NOT call any API's routine that would trigger the execution of a 4D command that displays a 4D Form from within the external process, such as ADD RECORD, DISPLAY RECORD, DISPLAY SELECTION, MODIFY SELECTION and DIALOG. Executing one of these 4th Dimension commands from within the external process may lead to a System Error.
· If the external process has user interface components it may open as many windows as is required. These windows belong to the external process and form the external processes' window list. For the cases where user interfaces components are required it is the responsibility of the 4D plug-in to set up its own menu bars. 4th Dimension automatically inserts the Apple (MacOS) or Help (Windows) menus.
The external process can be made invisible. For example, another process applying the 4D command HIDE PROCESS to the 4D plug-in process is valid. In such cases the visible field of the 4D plug-in window records are set to FALSE.
There are differences between Macintosh and Windows windows, as everyone knows.
If the programmer uses Macintosh routines and Altura Mac2Win to run its code under Windows, he can write its code "as usual" : the plug-in creates its windows and processes them into an event loop.
A Windows programmer can create and use windows and their WinProc as usual. 4th Dimension will give the correct event to winProc of the window that receive it. But remember that, as the windows were created from an external process and belongs to it, and not to 4th Dimension, this process must run the event loop that calls PA_WaitNextEvent and PA_IsProcessDying to keep a "reference" to the code that created the windows. There is no problem to add a winProc to the window by calling the Windows routine SetWindowLong.
Under MacOS, most of the Windows Manager routines are patched by 4th Dimension. In order to comply with the 4D multitasking environment the 4D plug-in must use them rather than directly accessing data structures or System Globals. For instance, the MacOS toolbox function call FrontWindow will return the front most window within the 4D plug-ins external process. Meanwhile, the System Global WindowList ($9D6) will contain a pointer to the front most window for the entire 4th Dimension active session.
In both cases, the programmer can use PA_NewWindow to create the window on both platform and insure that it will be added to the 4th Dimension application windows list.
Summary of an external process code
// No parameter, no returned value
// -----------------------------
void TheProcess (void)
{
PA_Event event;
char done = 0;
// Tell 4D the process exists and runs // ----------------------------------- PA_Yield()
while(!done)
{
// Check if the loop must end
// --------------------------
done = PA_IsProcessDying();
// Get event/Give hand to other processes
// --------------------------------------
if( !done && PA_WaitNextEvent( &event ) )
{
/* . . . */
}
// NOTE PA_Yield() can be used instead of PA_WaitNextEvent if there is no user interface
} // Last line of the code : tell 4D we we've finish PA_KillProcess();
}
Example
Sample code of an external process without user interface. This is the skeleton of what should be done by every external process. In this sample, the external process loops until there are 8 processes running.
To run this process, the plug-in simply calls:
aProcessNum = PA_NewProcess(SampleProcess, (32 * 1024), "Sample process")
Here is the code of the process :
/* =======================================================
Code of the sample external process
This external process loops until 8 processes at least are running.
During its loop, the process MUST call PA_WaitNextEvent to give
hand to the 4D scheduler. If it does not that, the user will think
its machine has froze.
Note that :
- PA_WaitNextEvent will always returns 0 when there is no
user interface
- You can call PA_Yield instead (we use this in this sample)
======================================================= */
void SampleProcess ()
{
char done = (char) 0;
long myProcess;
// ______________________________________ 1st "must be done" // Tell 4D to schedule us PA_YieldAbsolute();
// Get our number
myProcess = PA_GetCurrentProcessNumber();
// Main loop
while (!done)
{
// ______________________________________ 2nd "must be done"
// Give time to other processes
PA_Yield();
// Sleep a little bit, say 5 seconds
PA_PutProcessToSleep(myProcess, 300);
// If we are dying, leave the loop
// ______________________________________ 3rd "must be done"
done = PA_IsProcessDying();
if(!done)
{
if( PA_CountActiveProcess() >= 8 )
{
PA_Alert("There are at least 8 active processes");
done = (char) 1;
}
}
}
// ______________________________________ 4th "must be done" // At least, tell 4D we have finish PA_KillProcess(); } /* SampleProcess */
|
|
|
|
|
|
|
|
|