From: Gabriel Corona <gabriel.corona@loria.fr>
Date: Mon, 22 Feb 2016 10:21:44 +0000 (+0100)
Subject: [mc] Documentation of AddressSpace
X-Git-Tag: v3_13~755^2~3
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/5bcd7eea68c22b0cddc7b9ab8097eede4ea70409

[mc] Documentation of AddressSpace
---

diff --git a/src/mc/AddressSpace.hpp b/src/mc/AddressSpace.hpp
index d0c92b51e9..41f1f8bcf5 100644
--- a/src/mc/AddressSpace.hpp
+++ b/src/mc/AddressSpace.hpp
@@ -21,7 +21,12 @@ namespace mc {
 /** Pointer to a remote address-space (process, snapshot)
  *
  *  With this we can clearly identify the expected type of an address in the
- *  remote process whild avoiding to use native local pointers.
+ *  remote process while avoiding to use native local pointers.
+ *
+ *  Some operators (+/-) assume use the size of the underlying element. This
+ *  only works if the target applications is using the same target: it won't
+ *  work for example, when inspecting a 32 bit application from a 64 bit
+ *  model-checker.
  */
 template<class T> class remote_ptr {
   std::uint64_t address_;
@@ -30,6 +35,7 @@ public:
   remote_ptr(std::uint64_t address) : address_(address) {}
   remote_ptr(T* address) : address_((std::uintptr_t)address) {}
   std::uint64_t address() const { return address_; }
+
   operator bool() const
   {
     return address_;
@@ -126,14 +132,30 @@ const int ProcessIndexDisabled = -2;
  */
 const int ProcessIndexAny = 0;
 
+/** A given state of a given process (abstract base class)
+ *
+ *  Currently, this might either be:
+ *
+ *  * the current state of an existing process;
+ *
+ *  * a snapshot.
+ */
 class AddressSpace {
 private:
   Process* process_;
 public:
   enum ReadMode {
+
+    /** Copy the data to the given buffer */
     Normal,
+
     /** Allows the `read_bytes` to return a pointer to another buffer
-     *  where the data ins available instead of copying the data into the buffer
+     *  where the data is available instead of copying the data into the
+     *  buffer.
+     *
+     *  This adds quite a level of ugliness but it was found to more
+     *  efficient at some point. We should check if there is still
+     *  a noticeable different and get rid of it.
      */
     Lazy
   };
@@ -141,16 +163,27 @@ public:
   virtual ~AddressSpace();
 
   simgrid::mc::Process* process() const { return process_; }
+
+  /** Read data from the address space
+   *
+   *  @param buffer        target buffer for the data
+   *  @param size          number of bytes
+   *  @param address       remote source address of the data
+   *  @param process_index which process (used for SMPI privatization)
+   *  @param mode
+   */
   virtual const void* read_bytes(void* buffer, std::size_t size,
     remote_ptr<void> address, int process_index = ProcessIndexAny,
     ReadMode mode = Normal) const = 0;
 
+  /** Read a given data structure from the address space */
   template<class T> inline
   void read(T *buffer, remote_ptr<T> ptr, int process_index = ProcessIndexAny)
   {
     this->read_bytes(buffer, sizeof(T), ptr, process_index);
   }
 
+  /** Read a given data structure from the address space */
   template<class T> inline
   T read(remote_ptr<T> ptr, int process_index = ProcessIndexMissing)
   {