added alignment option and comments

Author: sy-c

src/MemoryPagesPool.cxx

@@ -1,40 +1,57 @@
 #include "MemoryPagesPool.h"
 
-MemoryPagesPool::MemoryPagesPool(size_t vPageSize, size_t vNumberOfPages, void *vBaseAddress, size_t vBaseSize,  ReleaseCallback vCallback) {
+MemoryPagesPool::MemoryPagesPool(size_t vPageSize, size_t vNumberOfPages, void *vBaseAddress, size_t vBaseSize,  ReleaseCallback vCallback, size_t pageAlign) {
+  // initialize members from parameters
   pageSize=vPageSize;
   numberOfPages=vNumberOfPages;
   baseBlockAddress=vBaseAddress;
   baseBlockSize=vBaseSize;
-  releaseBaseBlockCallback=vCallback;
-  
-  size_t sizeNeeded=pageSize * numberOfPages;
+  releaseBaseBlockCallback=vCallback;  
+
+  // if not specified, assuming base block size big enough to fit number of pages * page size
+  if (baseBlockSize==0) {
+    baseBlockSize=pageSize * numberOfPages;
+  }
+ 
+  // compute offset of first page to ensure aligned as requested
+  size_t offsetFirstPage=0;
+  if (pageAlign) {
+    size_t bytesExcess=((size_t)vBaseAddress) % pageAlign;
+    if (bytesExcess) {
+      offsetFirstPage=pageAlign-bytesExcess;
+    }
+  }
 
-  if (vBaseSize==0) {
-    baseBlockSize=sizeNeeded;
-  } else if (sizeNeeded>vBaseSize) {
-    numberOfPages=baseBlockSize/pageSize;
+  // if necessary, reduce number of pages to fit in available space
+  size_t sizeNeeded=pageSize * numberOfPages + offsetFirstPage;
+  if (sizeNeeded>baseBlockSize) {
+    numberOfPages=(baseBlockSize-offsetFirstPage)/pageSize;
   }
 
+  // create a fifo and store list of pages available
   pagesAvailable=std::make_unique<AliceO2::Common::Fifo<void *>>(numberOfPages);
   for (size_t i=0; i<numberOfPages; i++) {
-    void *ptr=&((char *)baseBlockAddress)[i*pageSize];
+    void *ptr=&((char *)baseBlockAddress)[offsetFirstPage+i*pageSize];
     pagesAvailable->push(ptr);
   }
 }
 
 MemoryPagesPool::~MemoryPagesPool() {
+  // if defined, use provided callback to release base block
   if ( (releaseBaseBlockCallback != nullptr) && (baseBlockAddress!=nullptr) ) {
     releaseBaseBlockCallback(baseBlockAddress);
   }
 }
 
 void *MemoryPagesPool::getPage() {
+  // get a page from fifo, if available
   void *ptr=nullptr;
   pagesAvailable->pop(ptr);
   return ptr;
 }
 
 void MemoryPagesPool::releasePage(void *address) {
+  // put back page in list of available pages
   pagesAvailable->push(address);
 }
 
@@ -57,8 +74,8 @@ size_t MemoryPagesPool::getBaseBlockSize() {
   return baseBlockSize;
 }
 
-
 std::shared_ptr<DataBlockContainer> MemoryPagesPool::getNewDataBlockContainer(void *newPage) {
+  // get a new page if none provided
   if (newPage==nullptr) {
     // get a new page from the pool
     newPage=getPage();
@@ -67,7 +84,8 @@ std::shared_ptr<DataBlockContainer> MemoryPagesPool::getNewDataBlockContainer(vo
     }
   }
 
-  // fill header
+  // fill header at beginning of page
+  // assuming payload is contiguous after header
   DataBlock *b=(DataBlock *)newPage;
   b->header.blockType=DataBlockType::H_BASE;
   b->header.headerSize=sizeof(DataBlockHeaderBase);

src/MemoryPagesPool.h

@@ -7,25 +7,41 @@
 #include <Common/DataBlockContainer.h>
 
 
-// optimized for 1-1 consumers (1 thread to get the page, 1 thread to release them)
-// no check on address of data pages pushed back
-// base address should be kept while object in use
+// This class creates a pool of data pages from a memory block
+// Optimized for 1-1 consumers (1 thread to get the page, 1 thread to release them)
+// No check is done on validity of address of data pages pushed back in queue
+// Base address should be kept while object is in use
 
 
 class MemoryPagesPool {
 
 public:
 
-  using ReleaseCallback = std::function<void(void*)>;
+  // prototype of function to release memory block
+  // argument is the baseAddress provided to constructor
   // NB: may use std::bind to add extra arguments
+  using ReleaseCallback = std::function<void(void*)>;
+
+  // constructor
+  // parameters:
+  // - size of each page (in bytes)
+  // - number of pages in the pool
+  // - base address of memory block where to create the pages
+  // - size of memory block in bytes (if zero, assuming it is big enough for page number * page size)
+  // - a release callback to be called at destruction time
+  // - page align is for alignment of 1st page (all pages are created contiguous)
+  MemoryPagesPool(size_t pageSize, size_t numberOfPages, void *baseAddress, size_t baseSize=0, ReleaseCallback callback=nullptr, size_t pageAlign=0);
 
- // constructor (args: size of each page and number of pages in the pool, base address where to create the pages)
-  MemoryPagesPool(size_t pageSize, size_t numberOfPages, void *baseAddress, size_t baseSize=0, ReleaseCallback callback=nullptr);
-  ~MemoryPagesPool(); // destructor
+  // destructor
+  ~MemoryPagesPool();
 
+  // methods to get and release page
+  // the two functions can be called concurrently without locking
+  // (but a lock is needed if calling the same function concurrently)
   void *getPage(); // get a new page from the pool (if available, nullptr if none)
   void releasePage(void *address); // insert back page to the pool after use, to make it available again
 
+  // access to variables
   size_t getPageSize(); // get the page size
   size_t getTotalNumberOfPages(); // get number of pages in pool
   size_t getNumberOfPagesAvailable(); //get number of pages currently available
@@ -43,7 +59,7 @@ class MemoryPagesPool {
   void * baseBlockAddress; // address of block containing all pages
   size_t baseBlockSize; // size of block containing all pages
 
-  ReleaseCallback releaseBaseBlockCallback;
+  ReleaseCallback releaseBaseBlockCallback; // the user function called in destructor, typically to release the baseAddress block.
 };