⇐ ↙ ↓ ⇑ ⇒ Contents Index

7.3 The HTCondor User and Job Log Reader API

  7.3.1 Constants and Enumerated Types
  7.3.2 Constructors and Destructors
  7.3.3 Initializers
  7.3.4 Primary Methods
  7.3.5 Accessors
  7.3.6 Methods for saving and restoring persistent reader state
  7.3.7 Save state to persistent storage
  7.3.8 Restore state from persistent storage
  7.3.9 API Reference
  7.3.10 Access to the persistent state data
  7.3.11 Future persistence API

HTCondor has the ability to log an HTCondor job’s significant events during its lifetime. This is enabled in the job’s submit description file with the Log command.

This section describes the API defined by the C++ ReadUserLog class, which provides a programming interface for applications to read and parse events, polling for events, and saving and restoring reader state.

7.3.1 Constants and Enumerated Types

The following define enumerated types useful to the API.

7.3.2 Constructors and Destructors

All ReadUserLog constructors invoke one of the initialize() methods. Since C++ constructors cannot return errors, an application using any but the default constructor should call isIinitialized() to verify that the object initialized correctly, and for example, had permissions to open required files.

Note that because the constructors cannot return status information, most of these constructors will be eliminated in the future. All constructors, except for the default constructor with no parameters, will be removed. The application will need to call the appropriate initialize() method.

7.3.3 Initializers

These methods are used to perform the initialization of the ReadUserLog objects. These initializers are used by all constructors that do real work. Applications should never use those constructors, should use the default constructor, and should instead use one of these initializer methods.

All of these functions will return false if there are problems such as being unable to open the log file, or true if successful.

7.3.4 Primary Methods

7.3.5 Accessors

7.3.6 Methods for saving and restoring persistent reader state

The ReadUserLog::FileState structure is used to save and restore the state of the ReadUserLog state for persistence. The application should always use InitFileState() to initialize this structure.

All of these methods take a reference to a state buffer as their only parameter.

All of these methods return true upon success.

7.3.7 Save state to persistent storage

To save the state, do something like this:

  ReadUserLog                reader;  
  ReadUserLog::FileState     statebuf;  
 
  status = ReadUserLog::InitFileState( statebuf );  
 
  status = reader.GetFileState( statebuf );  
  write( fd, statebuf.buf, statebuf.size );  
  ...  
  status = reader.GetFileState( statebuf );  
  write( fd, statebuf.buf, statebuf.size );  
  ...  
 
  status = UninitFileState( statebuf );

7.3.8 Restore state from persistent storage

To restore the state, do something like this:

  ReadUserLog::FileState     statebuf;  
  status = ReadUserLog::InitFileState( statebuf );  
 
  read( fd, statebuf.buf, statebuf.size );  
 
  ReadUserLog                reader;  
  status = reader.initialize( statebuf );  
 
  status = UninitFileState( statebuf );  
  ....

7.3.9 API Reference

7.3.10 Access to the persistent state data

If the application needs access to the data elements in a persistent state, it should instantiate a ReadUserLogStateAccess object.

7.3.11 Future persistence API

The ReadUserLog::FileState will likely be replaced with a new C++ ReadUserLog::NewFileState, or a similarly named class that will self initialize.

Additionally, the functionality of ReadUserLogStateAccess will be integrated into this class.

⇐ ↙ ↑ ⇑ ⇒ Contents Index