PA_SetGrowZone

version 2003

PA_SetGrowZone (growZoneHandler) → void *

Parameter Type Description
growZoneHandler void * → Pointer to a GrowZone routine
Function result void * ← The actual 4D Grow Zone Handler

Description

The routine PA_SetGrowZone tells 4D to use the routine gzHandler when it will be short of memory. It returns a pointer to the actual growZoneHandler routine in use.

The grow zone handler may only be called when 4th Dimension runs under Windows or MacOS 9.

The rules

for installing your GrowZone handler are as follows:

- PA_SetGrowZone MUST be called during the initialization phase, when the PluginMain routine receives the kInitPlugin selector. Installing a GrowZone Handler at another moment may lead to a system crash once the memory manager needs room.
- The code of the GrowZone Handler should dispose of all the memory it can and then it MUST call the original GrowZone Handler (it must keep it in a global variable) at the end of its code.
- PA_SetGrowZone MUST be called during the de-initialization phase, when the PluginMain routine receives the kDeinitPlugin selector, restoring the previously saved 4D GrowZone Handler.

IMPORTANT NOTE

In its GrowZoneHandler, the plug-in must never allocate memory (malloc, PA_NewHandle , GetResource, etc.), or do anything that could allocate memory (MessageBox under Windows, Alert under MacOS). It must only dispose of non-critical memory.

NOTE FOR WINDOWS PLUG-IN

This routine is usefull only if the plug-in uses Mac2Win (under Windows) to allocate memory or if the plug-in uses PA_NewHandle . If the plug-in uses only the Windows Memory Manager, its handles will be swapped on disk by Windows when necessary.

This may be a good moment to clear any temporary buffer.

Example

Installing and using a private grow zone handler: 

   void   *gPreviousGrowZone;
   
   void MyGrowZoneHandler ()
   {
      // Dispose of the max memory the plug-in can
      /* . . . DisposeHandle, ReleaseResource, free, GlobalFree . . .*/
      // At least, call the original 4D GrowZoneHandler
      gPreviousGrowZone();
   }
   
   void PluginMain( long selector, PA_PluginParameters params )
   {
      switch ( selector )
      {
         case kInitPlugin :
            // Install my GrowZoneHandler only at kInitPlugin time
            gPreviousGrowZone = PA_SetGrowZone( MyGrowZoneHandler );
            break;
   
         case kDeinitPlugin :
         {
            void*   ignore;
            // restore previous GrowZoneHandler only at kDeinitPlugin time
            ignore = PA_SetGrowZone( gPreviousGrowZone );
         }
         break;
      }
   }

See Also

No reference.

Error Handling

PA_GetLastError

always returns eER_NoErr