DUM Application Shutdown

From reSIProcate
Jump to navigation Jump to search

Graceful Shutdown[edit]

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 call dum->process during the shutdown, 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[edit]

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 call dum->process during the shutdown, 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.