added comments and some cleanup code

7 files changed, 52 insertions, 23 deletions

diff --git a/lib/CMakeLists.txt b/lib/CMakeLists.txt
index 6ec28c1..09fc704 100644
--- a/lib/CMakeLists.txt
+++ b/lib/CMakeLists.txt
@@ -14,7 +14,7 @@ list(APPEND gnuradio_core_sources
     ${CMAKE_CURRENT_SOURCE_DIR}/block_task.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/block_allocator.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/block_handlers.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/block_ports.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/port_handlers.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/hier_block.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/top_block.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/gr_block.cpp
diff --git a/lib/block_handlers.cpp b/lib/block_handlers.cpp
index 8bf137d..fcaa359 100644
--- a/lib/block_handlers.cpp
+++ b/lib/block_handlers.cpp
@@ -19,10 +19,14 @@
 
 using namespace gnuradio;
 
-void ElementImpl::handle_block_msg(const tsbe::TaskInterface &task_iface, const tsbe::Wax &msg)
-{
+void ElementImpl::handle_block_msg(
+    const tsbe::TaskInterface &task_iface,
+    const tsbe::Wax &msg
+){
     std::cout << "handle_block_msg in " << name << std::endl;
 
+    //a buffer has returned from the downstream
+    //(all interested consumers have finished with it)
     if (msg.type() == typeid(BufferReturnMessage))
     {
         const BufferReturnMessage &message = msg.cast<BufferReturnMessage>();
@@ -33,6 +37,7 @@ void ElementImpl::handle_block_msg(const tsbe::TaskInterface &task_iface, const
         return;
     }
 
+    //self kick, call the handle task method
     if (msg.type() == typeid(SelfKickMessage))
     {
         this->handle_task(task_iface);
diff --git a/lib/element.cpp b/lib/element.cpp
index e0269e7..addc04d 100644
--- a/lib/element.cpp
+++ b/lib/element.cpp
@@ -40,6 +40,12 @@ Element::Element(const std::string &name)
     this->set_output_signature(sig);
 }
 
+ElementImpl::~ElementImpl(void)
+{
+    if (this->executor) this->top_block_cleanup();
+    if (this->topology) this->hier_block_cleanup();
+}
+
 long Element::unique_id(void) const
 {
     return (*this)->unique_id;
diff --git a/lib/element_impl.hpp b/lib/element_impl.hpp
index 4742993..333bfae 100644
--- a/lib/element_impl.hpp
+++ b/lib/element_impl.hpp
@@ -34,23 +34,11 @@ namespace gnuradio
 
 struct ElementImpl
 {
-    ElementImpl(void)
-    {
-        //NOP
-    }
 
-    ~ElementImpl(void)
-    {
-        if (this->executor)
-        {
-            TopBlockMessage event;
-            event.what = TopBlockMessage::INERT;
-            this->executor.post_msg(event);
-        }
-        children.clear();
-    }
-
-    std::vector<boost::shared_ptr<Element> > children;
+    //deconstructor stuff
+    ~ElementImpl(void);
+    void top_block_cleanup(void);
+    void hier_block_cleanup(void);
 
     //stuff for when its a block
     std::string name;
@@ -109,6 +97,7 @@ struct ElementImpl
     tsbe::Block block;
     tsbe::Topology topology;
     tsbe::Executor executor;
+    std::vector<boost::shared_ptr<Element> > children;
     const tsbe::Element &get_elem(void) const
     {
         if (block) return block;
diff --git a/lib/hier_block.cpp b/lib/hier_block.cpp
index 47be7d0..3603612 100644
--- a/lib/hier_block.cpp
+++ b/lib/hier_block.cpp
@@ -32,6 +32,11 @@ HierBlock::HierBlock(const std::string &name):
     (*this)->topology = tsbe::Topology(config);
 }
 
+void ElementImpl::hier_block_cleanup(void)
+{
+    this->children.clear();
+}
+
 void HierBlock::connect(const Element &elem)
 {
     (*this)->topology.add_topology(elem->topology);
diff --git a/lib/block_ports.cpp b/lib/port_handlers.cpp
index a0d9276..2461b7d 100644
--- a/lib/block_ports.cpp
+++ b/lib/port_handlers.cpp
@@ -18,10 +18,14 @@
 
 using namespace gnuradio;
 
-void ElementImpl::handle_input_msg(const tsbe::TaskInterface &handle, const size_t index, const tsbe::Wax &msg)
-{
+void ElementImpl::handle_input_msg(
+    const tsbe::TaskInterface &handle,
+    const size_t index,
+    const tsbe::Wax &msg
+){
     std::cout << "handle_input_msg in " << name << std::endl;
 
+    //handle incoming stream buffer, push into the queue
     if (msg.type() == typeid(tsbe::Buffer))
     {
         if (this->block_state == BLOCK_STATE_DONE) return;
@@ -29,17 +33,23 @@ void ElementImpl::handle_input_msg(const tsbe::TaskInterface &handle, const size
         this->handle_task(handle);
         return;
     }
+
+    //handle incoming stream tag, push into the tag storage
     if (msg.type() == typeid(Tag))
     {
         this->input_tags[index].push_back(msg.cast<Tag>());
         this->input_tags_changed[index] = true;
         return;
     }
+
+    //store the token of the upstream producer
     if (msg.type() == typeid(Token))
     {
         this->token_pool.insert(msg.cast<Token>());
         return;
     }
+
+    //an upstream block declared itself done, recheck the token
     if (msg.type() == typeid(CheckTokensMessage))
     {
         if (this->input_queues.empty(index) and this->input_tokens[index].unique())
@@ -50,15 +60,22 @@ void ElementImpl::handle_input_msg(const tsbe::TaskInterface &handle, const size
     }
 }
 
-void ElementImpl::handle_output_msg(const tsbe::TaskInterface &handle, const size_t index, const tsbe::Wax &msg)
-{
+void ElementImpl::handle_output_msg(
+    const tsbe::TaskInterface &handle,
+    const size_t index,
+    const tsbe::Wax &msg
+){
     std::cout << "handle_output_msg in " << name << std::endl;
 
+    //store the token of the downstream consumer
     if (msg.type() == typeid(Token))
     {
         this->token_pool.insert(msg.cast<Token>());
         return;
     }
+
+
+    //a downstream block has declared itself done, recheck the token
     if (msg.type() == typeid(CheckTokensMessage))
     {
         if (this->output_tokens[index].unique())
diff --git a/lib/top_block.cpp b/lib/top_block.cpp
index cf450b5..e0751b5 100644
--- a/lib/top_block.cpp
+++ b/lib/top_block.cpp
@@ -37,6 +37,13 @@ TopBlock::TopBlock(const std::string &name):
     std::cout << "===================================================" << std::endl;
 }
 
+void ElementImpl::top_block_cleanup(void)
+{
+    TopBlockMessage event;
+    event.what = TopBlockMessage::INERT;
+    this->executor.post_msg(event);
+}
+
 void TopBlock::update(void)
 {
     this->start(); //ok to re-start, means update