Bugfix in BufferCache, added some security checks, plus minor stuff in doc/howtobuild.txt

git-svn-id: https://www4.informatik.uni-erlangen.de/i4svn/danceos/trunk/devel/fail@1323 8c4709b5-6ec9-48aa-a5cd-a96041d1645a

src/core/sal/BufferCache.hpp

@@ -3,11 +3,10 @@
 
 #include <stdlib.h>
 
-// FIXME: (Maybe) This should be located in utils, because
-//        it's "Fail*-independend"...?
-
 namespace fail {
 
+class EventList;
+
 /**
  * \class BufferCache
  *
@@ -15,11 +14,8 @@ namespace fail {
  *
  * This class is intended to serve as a kind of cache for the entirely STL-based,
  * untyped and therefore quite slow event handling mechanism of Fail*.
- * To keep the code easily readable, the buffer management methods
- * are less performant than the could be (remove() and erase() have linear complexity).
- * 
- * FIXME: This desription sounds like a contradiction...
- * (-> "quite slow event handling" vs. "are less performant than the could be")
+ * To keep the code easily readable, some buffer management methods
+ * perform suboptimally (remove() and erase() have linear complexity).
  * 
  * FIXME: Why not using std::vector? ("A simple dynamic array")
  */
@@ -28,21 +24,21 @@ class BufferCache {
 private:
 	// TODO: comments ("//!<") needed!
 	T *m_Buffer;
-	size_t m_BufferCount;
-protected:
+	int m_BufferCount;
 	/**
-	 * Changes the current length of the array. Should be inlined.
+	 * Changes m_BufferCount. Should be inlined.
 	 * @param new_count the new array length
 	 */
-	inline void setCount(size_t new_count) { m_BufferCount = new_count; }
+	inline void setCount(int new_count) { if(new_count >= 0) m_BufferCount = new_count; }
+protected:
 	/**
 	 * Reallocates the buffer. This implementation is extremely primitive,
 	 * but since the amount of entries is small,
 	 * this will not be significant, hopefully. Should be inlined.
 	 * @param new_size the new number of elements in the array
-	 * @return 0 if successful, an error code otherwise (ATM only 10 if malloc() fails)
+	 * @return 0 if successful, an error code otherwise (10 if realloc() fails, 20 for an invalid new size)
 	 */
-	inline int reallocate_buffer(size_t new_size);
+	inline int reallocate_buffer(int new_size);
 public:
 	BufferCache()
 		: m_Buffer(NULL), m_BufferCount(0) {}
@@ -50,19 +46,17 @@ public:
 	/**
 	 * Add an element to the array. The object pointed to remains untouched.
 	 * @param val the element to add
-	 * @return 0 if successful, an error code otherwise (ATM only 10 if malloc() fails)
 	 */
-	int add(T val);
+	void add(T val);
 	/**
 	 * Remove an element from the array. The object pointed to remains untouched.
 	 * @param val the element to remove
-	 * @return 0 if successful, an error code otherwise (ATM only 10 if malloc() fails)
 	 */
-	int remove(T val);
+	void remove(T val);
 	/**
 	 * Remove an element at a specific position. The object pointed to remains untouched.
 	 * @param val the element to remove
-	 * @return a pointer to the given element's successor if successful, -1 otherwise
+	 * @return a pointer to the given element's successor if successful, a negative value otherwise
 	 */
 	int erase(int i);
 	/**
@@ -74,18 +68,27 @@ public:
 	 * @param idx the position to retrieve the element from
 	 * @return the element at the given position
 	 */
-	inline T get(size_t idx) { return m_Buffer[idx]; }
+	inline T get(int idx) { return (idx >= 0 && idx < getCount() ? m_Buffer[idx] : NULL); }
 	/**
 	 * Set an element at a given position. Should be inlined.
 	 * @param idx the position to change an element at
 	 * @param val the new value of the given element
 	 */
-	inline void set(size_t idx, T val) { m_Buffer[idx] = val; }
+	inline void set(int idx, T val) { if(idx >= 0 && idx < getCount()) m_Buffer[idx] = val; }
 	/**
 	 * Retrieves the current length of the array. Should be inlined.
 	 * @return the array length
 	 */
-	inline size_t getCount() { return m_BufferCount; }
+	inline int getCount() { return m_BufferCount; }
+	/**
+	 * Acts as a replacement for EventList::makeActive, manipulating
+	 * the buffer cache exclusively. EventList::fireActiveEvents needs
+	 * to be called to fire the active events (see there).
+	 * This method is declared as a friend method in EventList.
+	 * @param idx the index of the event to trigger
+	 * @returns an updated index which can be used to update a loop counter
+	 */
+	int makeActive(EventList &ev_list, int idx);
 };
 
 } // end-of-namespace: fail