2 files changed, 74 insertions, 5 deletions

diff --git a/src/stable/myriad.cpp b/src/stable/myriad.cpp
index 5e511fd..492676e 100644
--- a/src/stable/myriad.cpp
+++ b/src/stable/myriad.cpp
@@ -129,6 +129,19 @@ Bu::MyriadStream Bu::Myriad::open( Bu::Myriad::StreamId iStream,
     return Bu::MyriadStream( *this, pStream, eMode );
 }
 
+Bu::Myriad::StreamId Bu::Myriad::allocate()
+{
+    Bu::MutexLocker l( mAccess );
+
+    Stream *pStream = new Stream( *this, ++iLastUsedIndex, 0 );
+    mhStream.lock();
+    hStream.insert( pStream->iStream, pStream );
+    mhStream.unlock();
+    bStructureChanged = true;
+
+    return pStream->iStream;
+}
+
 void Bu::Myriad::erase( Bu::Myriad::StreamId iStream )
 {
     // For now, let's prevent you from erasing a stream if it's open.
@@ -252,6 +265,19 @@ int32_t Bu::Myriad::getTotalUnusedBytes(int32_t iAssumeBlockSize ) const
     return iTotal;
 }
 
+Bu::Myriad::StreamIdList Bu::Myriad::getStreamList() const
+{
+    mhStream.lock();
+    StreamIdList lIds = hStream.getKeys();
+    mhStream.unlock();
+    lIds.sort();
+    if( lIds.first() == 0 )
+    {
+        lIds.eraseFirst();
+    }
+    return lIds;
+}
+
 Bu::BitString Bu::Myriad::buildBlockUseMap() const
 {
     Bu::MutexLocker l( mAccess );
@@ -264,10 +290,10 @@ Bu::BitString Bu::Myriad::buildBlockUseMap() const
     return bsMap;
 }
 
-Bu::Array<int32_t> Bu::Myriad::buildBlockMap() const
+Bu::Myriad::StreamIdArray Bu::Myriad::buildBlockMap() const
 {
     Bu::MutexLocker l( mAccess );
-    Bu::Array<int32_t> bm( iBlockCount );
+    StreamIdArray bm( iBlockCount );
     for( int j = 0; j < iBlockCount; j++ )
     {
         bm.append( -1 );
diff --git a/src/stable/myriad.h b/src/stable/myriad.h
index 6168aa2..5accd1e 100644
--- a/src/stable/myriad.h
+++ b/src/stable/myriad.h
@@ -31,10 +31,20 @@ namespace Bu
         };
     subExceptionDeclEnd();
 
+    /**
+     * Myriad Stream Multiplexer. This is a system that allows you to store
+     * many streams within a single backing stream. This is great for databases,
+     * caching, etc. It's fairly lightweight, and allows all streams to grow
+     * dynamically using a block-allocation scheme.  This is used extensively
+     * by the caching system and MyriadFs as well as other systems within
+     * libbu++.
+     */
     class Myriad
     {
     public:
         typedef int32_t StreamId;
+        typedef Bu::Array<StreamId> StreamIdArray;
+        typedef Bu::List<StreamId> StreamIdList;
         enum Mode : int32_t {
             None        = 0x00,
 
@@ -55,8 +65,9 @@ namespace Bu
 
     public:
         /**
-         * Open existing Myriad stream, or initialize a new one if it doesn't
-         * exist.
+         * Open existing Myriad container, or initialize a new one if the
+         * backing stream is empty. If other data is already in the provided
+         * backing stream an error is thrown.
          *
          * Myriad format V0
          *   0 -   3:  Myriad_MAGIC_CODE (0ad3fa84)
@@ -75,8 +86,32 @@ namespace Bu
                 int32_t iPreallocateBlocks=-1 );
         virtual ~Myriad();
 
+        /**
+         * Creates a new stream open in the specified eMode and, optionally,
+         * preallocates the specificed amount of space. The stream is zero
+         * bytes even if space is preallocated. The open stream is returned,
+         * ready for use. Use this if you don't care what the id is of the
+         * newly created stream.
+         */
         MyriadStream create( Mode eMode, int32_t iPreallocateBytes=-1 );
+
+        /**
+         * Open an existing stream or create a new stream with the specified
+         * id (iStream) with the specified eMode. This respects the normal file
+         * modes, see Bu::Myriad::Mode for details.
+         */
         MyriadStream open( StreamId iStream, Mode eMode );
+
+        /**
+         * Allocate a new stream but do not open it, just ensure it exists and
+         * return the id of the newly allocated stream.
+         */
+        StreamId allocate();
+
+        /**
+         * Erase the stream specified by iStream. This only can work when the
+         * stream is not open at the moment.
+         */
         void erase( StreamId iStream );
         void setSize( StreamId iStream, int32_t iNewSize );
         int32_t getSize( StreamId iStream ) const;
@@ -90,7 +125,15 @@ namespace Bu
         int32_t getTotalUsedBytes() const;
         int32_t getTotalUnusedBytes( int32_t iAssumeBlockSize=-1 ) const;
         Bu::BitString buildBlockUseMap() const;
-        Bu::Array<int32_t> buildBlockMap() const;
+        StreamIdArray buildBlockMap() const;
+        
+        /**
+         * Lists all stream ids that you are allowed to open. Technically there
+         * is always a zero stream, but it is used by Myriad for stream/block
+         * accounting. It works like a normal stream but you should not open
+         * it.
+         */
+        StreamIdList getStreamList() const;
 
         /**
          * Flush all caches to the backing stream, write all structural and