GNU Radio 3.6.0 C++ API
pmt_mgr.h
Go to the documentation of this file.
00001 /*
00002  * Copyright 2011-2012 Free Software Foundation, Inc.
00003  * 
00004  * This file is part of GNU Radio
00005  * 
00006  * GNU Radio is free software; you can redistribute it and/or modify
00007  * it under the terms of the GNU General Public License as published by
00008  * the Free Software Foundation; either version 3, or (at your option)
00009  * any later version.
00010  * 
00011  * GNU Radio is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  * 
00016  * You should have received a copy of the GNU General Public License
00017  * along with GNU Radio; see the file COPYING.  If not, write to
00018  * the Free Software Foundation, Inc., 51 Franklin Street,
00019  * Boston, MA 02110-1301, USA.
00020  */
00021 
00022 #ifndef INCLUDED_GRUEL_PMT_MGR_H
00023 #define INCLUDED_GRUEL_PMT_MGR_H
00024 
00025 #include <gnuradio/extras/api.h>
00026 #include <gruel/pmt.h>
00027 
00028 namespace pmt{
00029 
00030 /*
00031  * ------------------------------------------------------------------------
00032  *      Manage a collection of PMTs -> memory wise
00033  *
00034  * When a PMT reference count becomes zero, the pmt and contents is deleted.
00035  * With a manager, the PMT will not be deleted, but released to the manager.
00036  * Then, the PMT can be acquired again for re-use by the user.
00037  *
00038  * This offers 2 benefits:
00039  *  - Avoids expensive memory allocation overhead (re-use is key)
00040  *  - An upstream producer can block until resources become released
00041  * ------------------------------------------------------------------------
00042  */
00043 
00044 class GR_EXTRAS_API pmt_mgr{
00045 public:
00046     typedef boost::shared_ptr<pmt_mgr> sptr;
00047 
00048     //! Make a new pmt manager object
00049     static sptr make(void);
00050 
00051     /*!
00052      * \brief Set a pmt to the specified manager.
00053      *
00054      * \param x any other object of type pmt
00055      */
00056     virtual void set(pmt_t x) = 0;
00057 
00058     /*!
00059      * \brief Unset a pmt from the specified manager.
00060      *
00061      * \param x any other object of type pmt
00062      */
00063     virtual void reset(pmt_t x) = 0;
00064 
00065     /*!
00066      * \brief Acquire a pmt from the manager.
00067      *
00068      * The order of managed pmts retrieved by this function is not guaranteed.
00069      * For this reason, the user may want to keep a manager homogeneous.
00070      * Ex: This manager only manages blobs of size 1500 bytes.
00071      *
00072      * \param block when true, block until pmt available
00073      * \return a managed pmt or empty sptr if not available
00074      */
00075     virtual pmt_t acquire(bool block = true) = 0;
00076 
00077 };
00078 
00079 }
00080 
00081 #endif /* INCLUDED_GRUEL_PMT_MGR_H */