Sans Pareil Technologies, Inc.

Key To Your Business

File Event Notification (FEN)



File Event Notification is an event source under the Event Ports framework that was introduced in Solaris 10. FEN can be used to monitor files or directories for various types of events - modification, attribute change, access etc. SPT uses FEN in various caching/queueing systems when associated files/directories are modified by external processes. Here we will demonstrate a Poco Runnable based monitor class that was adapted from a FEN blog entry.

FileMonitor Definition

The FileMonitor class implements a Poco::Runnable interface and is used to monitor specified files for modification events. The primary method exposed by this class is a monitor( const char* ) method which is used to register the specified file with FEN. Note that in this implementation we do not prevent duplicate requests for the same resource to be monitored, since in our case the callers ensure that only unique files are monitored. A more generic implementation would maintain a local hash map to ensure this.

When a FEN notification is received for a file being monitored, the registered delegate is notified of the event. The delegate implementation may allow only a single notification to a caller, or maintain a list of callers to notify. The stop() method is used to close the event port and stop all monitoring.

    1: #pragma once
    2:
    3: #include <servlet/model/FileMonitorDelegate.h>
    4:
    5: #include <Poco/Logger.h>
    6: #include <Poco/Runnable.h>
    7:
    8: using Poco::Logger;
    9: using Poco::Runnable;
   10:
   11: #include <port.h>
   12: #include <sys/stat.h>
   13:
   14: namespace spt
   15: {
   16:   namespace servlet
   17:   {
   18:     namespace model
   19:     {
   20:       class FileMonitor : public Runnable
   21:       {
   22:       public:
   23:         FileMonitor( FileMonitorDelegate& );
   24:
   25:         virtual void run();
   26:         void stop();
   27:         void monitor( const char* );
   28:
   29:       private:
   30:         int port;
   31:         FileMonitorDelegate& delegate;
   32:         static Logger& logger;
   33:
   34:         struct fileinfo
   35:         {
   36:           struct file_obj fobj;
   37:           int events;
   38:           int port;
   39:         };
   40:
   41:         /** Process file modification event notifications */
   42:         void processEvent( struct fileinfo*, int );
   43:       };
   44:     }
   45:   }
   46: }

FileMonitorDelegate Definition

A FileMonitorDelegate implementation is registered with a FileMonitor when it is instantiated. The FileMonitor invokes the fileModified( const QString ) method on the delegate with the path of the file that was modified. The delegate implementation may then take appropriate action, or notify a list of observers as the case may be.

    1: #pragma once
    2:
    3: #include <QtCore/QString>
    4:
    5: namespace spt
    6: {
    7:   namespace servlet
    8:   {
    9:     namespace model
   10:     {
   11:       class FileMonitorDelegate
   12:       {
   13:       public:
   14:         virtual void fileModified( const QString ) = 0;
   15:       };
   16:     }
   17:   }
   18: }

FileMonitor Implementation

The FileMonitor implementation retrieves the port to monitor from the Event Port framework in its constructor. The Runnable:run() method implementation continually monitors the port using the port_get() function. The stop() method closes the port, which will then cause the run() method to terminate.

Callers register files they wish to monitor through the monitor( const char* ) method. This method allocates a new instance of the fileinfo structure and sets the event of interest to FILE_MODIFIED. It then invokes the processEvent() method which performs some error checking before using the port_associate() function to register with FEN for file modification event notifications. The run() method continually polls the port using port_get() and notifies the delegate when there is a notification.

    1: #include <servlet/model/FileMonitor.h>
    2: #include <QtCore/QString>
    3:
    4: using spt::servlet::model::FileMonitorDelegate;
    5: using Poco::format;
    6: using std::string;
    7:
    8: Logger &spt::servlet::model::FileMonitor::logger =
    9:     Logger::get( "spt.servlet.model.FileMonitor" );
   10:
   11:
   12: spt::servlet::model::FileMonitor::FileMonitor( FileMonitorDelegate& d ) :
   13:   port( -1 ), delegate( d )
   14: {
   15:   if ( ( port = port_create() ) == -1 )
   16:   {
   17:     logger.warning( "Unable to create file event notification port" );
   18:   }
   19: }
   20:
   21:
   22: void spt::servlet::model::FileMonitor::stop()
   23: {
   24:   if ( port != -1 ) close( port );
   25: }
   26:
   27:
   28: void spt::servlet::model::FileMonitor::run()
   29: {
   30:   if ( port == -1 ) return;
   31:
   32:   port_event_t pe;
   33:
   34:   while ( ! port_get( port, &pe, NULL ) )
   35:   {
   36:     switch ( pe.portev_source )
   37:     {
   38:     case PORT_SOURCE_FILE:
   39:       processEvent( (struct fileinfo*) pe.portev_object, pe.portev_events );
   40:       break;
   41:     default:
   42:       logger.warning( "Event from unexpected source" );
   43:     }
   44:   }
   45:
   46:   logger.information( "FileMonitor thread exiting" );
   47: }
   48:
   49:
   50: void spt::servlet::model::FileMonitor::monitor( const char* filePath )
   51: {
   52:   struct fileinfo* finf = new fileinfo;
   53:   if ( ! finf )
   54:   {
   55:     logger.error( format( "Unable to allocate memory for fileinfo struct for file: %s", string( filePath ) ) );
   56:     return;
   57:   }
   58:
   59:   if ( ( finf->fobj.fo_name = strdup( filePath ) ) == NULL )
   60:   {
   61:     logger.error( format( "Unable to copy file path into fileinfo struct for file: %s", string( filePath ) ) );
   62:     delete finf;
   63:     return;
   64:   }
   65:
   66:   finf->events = FILE_MODIFIED;
   67:   finf->port = port;
   68:   logger.information( format( "Adding %s to file event notification.", string( filePath ) ) );
   69:   processEvent( finf, 0 );
   70: }
   71:
   72:
   73: void spt::servlet::model::FileMonitor::processEvent( struct fileinfo* finf, int revents )
   74: {
   75:   struct file_obj* fobjp = &finf->fobj;
   76:   int port = finf->port;
   77:   struct stat sb;
   78:
   79:   if ( ! ( revents & FILE_EXCEPTION ) && stat( fobjp->fo_name, &sb ) == -1 )
   80:   {
   81:     logger.warning(
   82:         format( "Failed to stat file: %s - errno %d", string( fobjp->fo_name ), errno ) );
   83:     free( finf->fobj.fo_name );
   84:     delete finf;
   85:     return;
   86:   }
   87:
   88:   if ( revents & FILE_EXCEPTION )
   89:   {
   90:     free( finf->fobj.fo_name );
   91:     delete finf;
   92:     return;
   93:   }
   94:
   95:   if ( revents & FILE_MODIFIED )
   96:   {
   97:     logger.information( format( "%s modified", string( fobjp->fo_name ) ) );
   98:     delegate.fileModified( QString( fobjp->fo_name ) );
   99:   }
  100:
  101:   fobjp->fo_atime = sb.st_atim;
  102:   fobjp->fo_mtime = sb.st_mtim;
  103:   fobjp->fo_ctime = sb.st_ctim;
  104:
  105:   if ( port_associate( port, PORT_SOURCE_FILE,
  106:       (uintptr_t) fobjp, finf->events, static_cast<void*>( finf ) ) == -1 )
  107:   {
  108:     logger.warning(
  109:         format( "Failed to register file: %s - errno %d", string( fobjp->fo_name ), errno ) );
  110:     free( finf->fobj.fo_name );
  111:     delete finf;
  112:   }
  113: }

Sample Caller

A sample caller class would look something like the following:

    1: #include <servlet/model/FileMetaData.h>
    2: #include <servlet/model/FileMonitorDelegate.h>
    3: #include <Poco/File.h>
    4: #include <Poco/RWLock.h>
    5: #include <Poco/Thread.h>
    6: #include <QtCore/QHash>
    7: #include <QtCore/QString>
    8:
    9: using Poco::File;
   10: using Poco::RWLock;
   11: using Poco::ScopedWriteRWLock;
   12: using Poco::Thread;
   13:
   14: class FileMonitorClient : public FileMonitorDelegate
   15: {
   16: public:
   17:   FileMonitorClient() :  monitor( new FileMonitor( *this ) )
   18:   {
   19:     thread.start( *monitor );
   20:
   21:     const char* name1 = "/tmp/file1.txt";
   22:     File f1( name1 );
   23:     cache->insert( name1, f1 );
   24:     monitor->monitor( name1 );
   25:
   26:     const char* name2 = "/tmp/file2.txt";
   27:     File f2( name2 );
   28:     cache->insert( name2, f2 );
   29:     monitor->monitor( name2 );
   30:   }
   31:
   32:   ~FileMonitorClient()
   33:   {
   34:     monitor->stop();
   35:     thread.join();
   36:     delete monitor;
   37:   }
   38:
   39:   void fileModified( const QString name )
   40:   {
   41:     ScopedWriteRWLock wl( lock );
   42:     File f = cache->take( name );
   43:     // refresh and put back into cache as appropriate
   44:   }
   45:
   46: private:
   47:   FileMonitor* monitor;
   48:   QHash<QString,File> cache;
   49:   RWLock lock;
   50:   Thread thread;
   51: }


We have demonstrated how we use the Solaris File Event Notification (FEN) event source under the Event Port framework to monitor for external modifications to files of interest. This is used as part of application specific caching logic. When an external modification event is trapped, the stale entry is removed/refreshed in the cache.