DUM Application Shutdown

From reSIProcate
Revision as of 10:01, 16 November 2007 by Sgodin (talk | contribs)
Jump to navigation Jump to search

Graceful Shutdown

Use the DialogUsageManager::shutdown API to gracefully shutdown DUM. This method takes an application provided DumShutdownHandler as an argument. The application should derive it's own class from DumShutdownHandler and pass this into the shutdown call. The callback interface on this class can be used by the application to know when DUM has completed it's graceful shutdown. At this time it is safe for the application to delete the stack object.

Example application shutdown handler:

class MyShutdownHandler : public DumShutdownHandler
{
   public:
      MyShutdownHandler() : mShutDown(false) { }
      virtual ~MyShutdownHandler(){} 

      bool isShutdown() { return mShutdown; }
      virtual void onDumCanBeDeleted() 
      {
         cout << "onDumCanBeDeleted was called" << endl;
         mShutDown = true;
      }
   private:
      volatile bool mShutdown;
};

In order for the graceful shutdown process to complete the application MUST first end all usages (InviteSessions, Registrations, Subscriptions, etc.). The shutdown will only complete once all usages have been destroyed. To help troubleshoot issues with shutdowns that do not complete you can examine the resip log file at DebugLog level, look for the lines starting at: "Shutdown waiting for all usages to be deleted...".

Under the hood - the shutdown command calls shutdownWhenEmpty on the DUM HandleManager. Once all usages are ended, thus all handles are removed, the DialogUsageManager will request that the stack removes DUM as TU. This will cause the stack to generate a TransactionUserRemoved message on DUM fifo, that triggers the onDumCanBeDeleted callback on the ShutdownHandler.

NOTE: It is important the application continues to process the select loop during this process, in order to allow the usages to destroy gracefully and for DUM to see the final removed message from the stack. Once the onDumCanBeDeleted callback is called, the application should break out of the process loop and is free to delete the stack object.

See dum/test/BasicCall.cxx for an example of this process.


Forced Shutdown

Use the DialogUsageManager::forceShutdown API to forcefully shutdown DUM. This method takes an application provided DumShutdownHandler as an argument. The application should derive it's own class from DumShutdownHandler and pass this into the forceShutdown call. This will shutdown without waiting for all usages to gracefully end. This can cause calls in progress not to end, or active registrations not be unregistered.

NOTE: It is important the application continues to process the select loop during this process, in order to allow DUM to receive the final removed message from the stack. Once the onDumCanBeDeleted callback is called, the application should break out of the process loop and is free to delete the stack object.