summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBent Bisballe Nyeng <deva@aasimon.org>2015-04-11 12:11:16 +0200
committerBent Bisballe Nyeng <deva@aasimon.org>2016-01-20 13:22:09 +0100
commit554d519b7b2504b761782300d647868fe81467fc (patch)
tree6e1a0a74988efc1f4a7275a094b63ec5f50a140f
parenta91513d1111f13c18ec96505bbb2c3c6ed4db9d6 (diff)
Add documentation of CacheManager public API.
-rw-r--r--src/cachemanager.h99
1 files changed, 74 insertions, 25 deletions
diff --git a/src/cachemanager.h b/src/cachemanager.h
index 264f644..f28eb5f 100644
--- a/src/cachemanager.h
+++ b/src/cachemanager.h
@@ -44,42 +44,91 @@
class AudioFile;
typedef int cacheid_t;
+
+//TODO:
+// 1: Move nodata initialisation to init method.
+// 2: Make semaphore in thread to block init call until thread has been started.
+
+//// next
+// Pre: preloaded contains 2 x framesize. chunk size is framesize.
+// allocate 2 chunks and copy initial_samples_needed to first buffer from
+// preloaded data and enough to fill up the second buffer from preloaded
+// returns the first buffer and its size in &size.
+// get id from "free stack" and store pointers to buffers in id vector.
+// event: open sndfile handle (if not already open) and increase refcount
+
+//// next
+// Return which ever buffer is the front, swap them and add event to load the
+// next chunk.
+
+//// close
+// decrement file handle refcounter and close file if it is 0.
+// free the 2 buffers
+// (do not erase from the id vector), push index to
+// "free stack" for reuse.
+
class CacheManager : public Thread {
public:
+ /**
+ * Empty constructor...
+ */
CacheManager();
+
+ /**
+ * Destroy object and stop thread if needed.
+ */
~CacheManager();
- void init(int poolsize);
+ /**
+ * Initialise cache manager and allocate needed resources
+ * This method starts the cache manager thread.
+ * This method blocks until the thread has been started.
+ * @param poolsize The maximum number of parellel events supported.
+ */
+ void init(size_t poolsize);
+
+ /**
+ * Stop thread and clean up resources.
+ * This method blocks until the thread has stopped.
+ */
void deinit();
- void thread_main();
-
- // Pre: preloaded contains 2 x framesize. chunk size is framesize.
- // allocate 2 chunks and copy initial_samples_needed to first buffer from
- // preloaded data and enough to fill up the second buffer from preloaded
- // returns the first buffer and its size in &size.
- // get id from "free stack" and store pointers to buffers in id vector.
- // event: open sndfile handle (if not already open) and increase refcount
- sample_t *open(AudioFile *file, size_t initial_samples_needed, int channel, cacheid_t &new_id);
-
- // Return which ever buffer is the front, swap them and add event to load the
- // next chunk.
+ /**
+ * Register new cache entry.
+ * Prepares an entry in the cache manager for future disk streaming.
+ * @param file A pointer to the file which is to be streamed from.
+ * @param initial_samples_needed The number of samples needed in the first
+ * read that is not nessecarily of framesize. This is the number of samples
+ * from the input event offset to the end of the frame in which it resides.
+ * initial_samples_needed <= framesize.
+ * @param channel The channel to which the cache id will be bound.
+ * @param [out] new_id The newly created cache id.
+ * @return A pointer to the first buffer containing the
+ * 'initial_samples_needed' number of samples.
+ */
+ sample_t *open(AudioFile *file, size_t initial_samples_needed, int channel,
+ cacheid_t &new_id);
+
+ /**
+ * Get next buffer.
+ * Returns the next buffer for reading based on cache id.
+ * This function will (if needed) schedule a new disk read to make sure that
+ * data is available in the next call to this method.
+ * @param id The cache id to read from.
+ * @param [out] size The size of the returned buffer.
+ * @return A pointer to the buffer.
+ */
sample_t *next(cacheid_t id, size_t &size);
- // decrement file handle refcounter and close file if it is 0.
- // free the 2 buffers
- // (do not erase from the id vector), push index to
- // "free stack" for reuse.
+ /**
+ * Unregister cache entry.
+ * Close associated file handles and free associated buffers.
+ * @param id The cache id to close.
+ */
void close(cacheid_t id);
- // id vector:
- // {
- // AudioFile*
- // channel
- // buffer1, buffer2
- // position
- // (ready?)
- // }
+ ///! Internal thread main method - needs to be public.
+ void thread_main();
private: