Added a bunch of comments to TapeReadSingleThread, TapeReadTask, TapeWriteTask, MemBlock

castor/tape/tapeserver/daemon/MemBlock.hpp

@@ -39,26 +39,35 @@ namespace daemon {
  */
 class MemBlock {
 public:
-  static const int uninitialised_value = -1;
+  /**
+   * COnstrucor 
+   * @param id the block ID for its whole life
+   * @param capacity the capacity (in byte) of the embed payload 
+   */
   MemBlock(const int id, const size_t capacity) : 
   m_memoryBlockId(id),m_payload(capacity){
     reset();
   }
   
-  
+  /**
+   * Mark this block as failed ie 
+   * m_failed is true, m_fileBlock and m_tapeFileBlock are set at -1
+   * Other members do not change
+   */
   void markAsFailed(){
     m_failed = true;
     m_fileBlock = -1;
     m_tapeFileBlock = -1;
   }
   /**
-   * Reset the values of all the 
+   * Reset all the members.
+   * Numerical ones are set at -1.and m_failed to false.
    */
   void reset() throw() {
-    m_fileid = uninitialised_value;
-    m_fileBlock = uninitialised_value;
-    m_fSeq = uninitialised_value;
-    m_tapeFileBlock = uninitialised_value;
+    m_fileid = -1;
+    m_fileBlock = -1;
+    m_fSeq = -1;
+    m_tapeFileBlock = -1;
     m_failed=false;
   }
   /** Unique memory block id */

castor/tape/tapeserver/daemon/TapeReadSingleThread.hpp

@@ -37,16 +37,36 @@ namespace castor {
 namespace tape {
 namespace tapeserver {
 namespace daemon {
+  
+  /**
+   * This class will execute the different tape read tasks.
+   * 
+   */
 class TapeReadSingleThread : public TapeSingleThreadInterface<TapeReadTaskInterface>{
 public:
+  /**
+   * 
+   * @param drive The drive which holds all we need in order to read later data from it
+   * @param vid Volume ID (tape number)
+   * @param maxFilesRequest : the maximul number of file the task injector may 
+   * ask to the client in a single requiest, this is used for the feedback loop
+   * @param lc : log context, for logging purpose
+   */
   TapeReadSingleThread(castor::tape::drives::DriveInterface & drive,
           const std::string vid, uint64_t maxFilesRequest,
           castor::log::LogContext & lc): 
    TapeSingleThreadInterface<TapeReadTaskInterface>(drive, vid, lc),
    m_maxFilesRequest(maxFilesRequest) {}
+   
    void setTaskInjector(TaskInjector * ti) { m_taskInjector = ti; }
 
 private:
+  
+  /**
+   * Pop a task from its tasks and if there is not enought tasks left, it will 
+   * ask the task injector for more 
+   * @return m_tasks.pop();
+   */
   TapeReadTaskInterface * popAndRequestMoreJobs() {
     castor::tape::threading::BlockingQueue<TapeReadTaskInterface *>::valueRemainingPair 
       vrp = m_tasks.popGetSize();
@@ -98,6 +118,8 @@ private:
   }
   
   uint64_t m_maxFilesRequest;
+  
+  castor::tape::tapeserver::daemon::TaskInjector * m_taskInjector;
 };
 }
 }

castor/tape/tapeserver/daemon/TapeReadTask.hpp

@@ -35,19 +35,37 @@ namespace castor {
 namespace tape {
 namespace tapeserver {
 namespace daemon {
+  
+  /**
+   * This class is in charge of 
+   * 
+   */
 class TapeReadTask: public TapeReadTaskInterface {
 public:
+  /**
+   * COnstructor
+   * @param ftr The file being recalled. We acquire the ownership on the pointer
+   * @param destination the task that will consume the memory blocks
+   * @param mm The memory manager to get free block
+   */
   TapeReadTask(castor::tape::tapegateway::FileToRecallStruct * ftr,
     DataConsumer & destination, RecallMemoryManager & mm): 
     m_fileToRecall(ftr), m_fifo(destination), m_mm(mm) {}
     
+    /**
+     * @param rs the read session holding all we need to be able to read from the tape
+     * @param lc the log context for .. logging purpose
+     * The actual function that will do the job.
+     * The main loop is :
+     * Acquire a free memory block from the memory manager , fill it, push it 
+     */
   virtual void execute(castor::tape::tapeFile::ReadSession & rs,
     castor::log::LogContext & lc) {
+
     using castor::log::Param;
     typedef castor::log::LogContext::ScopedParam ScopedParam;
-    // Placeholder for the tape file read
     
-    // Set the common context for all the omming logs (file info)
+    // Set the common context for all the coming logs (file info)
     ScopedParam sp0(lc, Param("NSHOSTNAME", m_fileToRecall->nshost()));
     ScopedParam sp1(lc, Param("NSFILEID", m_fileToRecall->fileid()));
     ScopedParam sp2(lc, Param("BlockId", castor::tape::tapeFile::BlockId::extract(*m_fileToRecall)));
@@ -56,8 +74,11 @@ public:
     
     // Read the file and transmit it
     bool stillReading = true;
+    //for counting how many mem blocks have used and how many tape blocks
+    //(because one mem block can hold several tape blocks
     int fileBlock = 0;
     int tapeBlock = 0;
+    
     MemBlock* mb=NULL;
     try {
       std::auto_ptr<castor::tape::tapeFile::ReadFile> rf(openReadFile(rs,lc));
@@ -125,7 +146,12 @@ public:
   }
 private:
   
-  // Open the file and manage failure (if any)
+  /** 
+   * Open the file on the tape. In case of failure, log and throw
+   * Copying the auto_ptr on the calling point will give us the ownership of the 
+   * object.
+   * @return if successful, return an auto_ptr on the ReadFile we want
+   */
   std::auto_ptr<castor::tape::tapeFile::ReadFile> openReadFile(
   castor::tape::tapeFile::ReadSession & rs, castor::log::LogContext & lc){
 
@@ -145,8 +171,20 @@ private:
     }
     return rf;
   }
+  
+  /**
+   * All we need to know about the file we are recalling
+   */
   std::auto_ptr<castor::tape::tapegateway::FileToRecallStruct> m_fileToRecall;
+  
+  /**
+   * The task (seen as a Y) that will consume all the blocks we read
+   */
   DataConsumer & m_fifo;
+  
+  /**
+   *  The MemoryManager from whom we get free memory blocks 
+   */
   RecallMemoryManager & m_mm;
 
 };

castor/tape/tapeserver/daemon/TapeWriteTask.cpp

@@ -38,19 +38,26 @@ namespace tape {
 namespace tapeserver {
 namespace daemon {
 
-
+//------------------------------------------------------------------------------
+// Constructor
+//------------------------------------------------------------------------------
   TapeWriteTask::TapeWriteTask(int blockCount, tapegateway::FileToMigrateStruct* file,
           MigrationMemoryManager& mm,castor::tape::threading::AtomicFlag& errorFlag): 
   m_fileToMigrate(file),m_memManager(mm), m_fifo(blockCount),
           m_blockCount(blockCount),m_errorFlag(errorFlag)
   {
+    //register its fifo to the memory manager as a client in order to get mem block
     mm.addClient(&m_fifo); 
   }
-
+//------------------------------------------------------------------------------
+// fileSize
+//------------------------------------------------------------------------------
    int TapeWriteTask::fileSize() { 
     return m_fileToMigrate->fileSize(); 
   }
-  
+//------------------------------------------------------------------------------
+// execute
+//------------------------------------------------------------------------------  
    void TapeWriteTask::execute(castor::tape::tapeFile::WriteSession & session,
            MigrationReportPacker & reportPacker,castor::log::LogContext& lc) {
     using castor::log::LogContext;
@@ -120,22 +127,30 @@ namespace daemon {
       reportPacker.reportFailedJob(*m_fileToMigrate,e.getMessageValue(),e.code());
     } 
    }
-    
+//------------------------------------------------------------------------------
+// getFreeBlock
+//------------------------------------------------------------------------------    
   MemBlock * TapeWriteTask::getFreeBlock() { 
     return m_fifo.getFreeBlock(); 
   }
   
-
+//------------------------------------------------------------------------------
+// pushDataBlock
+//------------------------------------------------------------------------------   
    void TapeWriteTask::pushDataBlock(MemBlock *mb) {
     castor::tape::threading::MutexLocker ml(&m_producerProtection);
     m_fifo.pushDataBlock(mb);
   }
   
-
+//------------------------------------------------------------------------------
+// Destructor
+//------------------------------------------------------------------------------   
    TapeWriteTask::~TapeWriteTask() {
     castor::tape::threading::MutexLocker ml(&m_producerProtection);
   }
-
+//------------------------------------------------------------------------------
+// openWriteFile
+//------------------------------------------------------------------------------   
    std::auto_ptr<tapeFile::WriteFile> TapeWriteTask::openWriteFile(
    tape::tapeFile::WriteSession & session, log::LogContext& lc){
      std::auto_ptr<tape::tapeFile::WriteFile> output;

castor/tape/tapeserver/daemon/TapeWriteTask.hpp

@@ -127,6 +127,10 @@ private:
    */
   int m_blockCount;
   
+  /**
+   * A shared flag among the the tasks and the task injector, set as true as soon
+   * as task failed to do its job 
+   */
   castor::tape::threading::AtomicFlag& m_errorFlag;
 };