- Generated on Mon Sep 22 2014 16:09:01 for GNU Radio 3.7.2 C++ API by
1.8.6
|
GNU Radio 3.7.2 C++ API
|
Polymorphic Types are opaque data types that are designed as generic containers of data that can be safely passed around between blocks and threads in GNU Radio. They are heavily used in the stream tags and message passing interfaces. The most complete list of PMT function is, of course, the source code, specifically the header file pmt.h. This manual page summarizes the most important features and points of PMTs.
All PMTs are of the type pmt::pmt_t. This is an opaque container and PMT functions must be used to manipulate and even do things like compare PMTs. PMTs are also immutable (except PMT vectors). We never change the data in a PMT; instead, we create a new PMT with the new data. The main reason for this is thread safety. We can pass PMTs as tags and messages between blocks and each receives its own copy that we can read from. However, we can never write to this object, and so if multiple blocks have a reference to the same PMT, there is no possibility of thread-safety issues of one reading the PMT data while another is writing the data. If a block is trying to write new data to a PMT, it actually creates a new PMT to put the data into. Thus we allow easy access to data in the PMT format without worrying about mutex locking and unlocking while manipulating them.
PMTs can represent the following:
The PMT library also defines a set of functions that operate directly on PMTs such as:
The constants in the PMT library are:
Use pmt.h for a complete guide to the list of functions used to create PMTs and get the data from a PMT. When using these functions, remember that while PMTs are opaque and designed to hold any data, the data underneath is still a C++ typed object, and so the right type of set/get function must be used for the data type.
Typically, a PMT object can be made from a scalar item using a call like "pmt::from_<type>". Similarly, when getting data out of a PMT, we use a call like "pmt::to_<type>". For example:
As a side-note, making a PMT from a complex number is not obvious:
Pairs, dictionaries, and vectors have different constructors and ways to manipulate them, and these are explained in their own sections.
PMTs have a way of representing short strings. These strings are actually stored as interned symbols in a hash table, so in other words, only one PMT object for a given string exists. If creating a new symbol from a string, if that string already exists in the hash table, the constructor will return a reference to the existing PMT.
We create strings with the following functions, where the second function, pmt::intern, is simply an alias of the first.
The string can be retrieved using the inverse function:
The PMT library comes with a number of functions to test and compare PMT objects. In general, for any PMT data type, there is an equivalent "pmt::is_<type>". We can use these to test the PMT before trying to access the data inside. Expanding our examples above, we have:
PMT dictionaries and lists of key:value pairs. They have a well-defined interface for creating, adding, removing, and accessing items in the dictionary. Note that every operation that changes the dictionary both takes a PMT dictionary as an argument and returns a PMT dictionary. The dictionary used as an input is not changed and the returned dictionary is a new PMT with the changes made there.
The following is a list of PMT dictionary functions. Click through to get more information on what each does.
This example does some basic manipulations of PMT dictionaries in Python. Notice that we pass the dictionary a and return the results to a. This still creates a new dictionary and removes the local reference to the old dictionary. This just keeps our number of variables small.
PMT vectors come in two forms: vectors of PMTs and vectors of uniform data. The standard PMT vector is a vector of PMTs, and each PMT can be of any internal type. On the other hand, uniform PMTs are of a specific data type which come in the form:
That is, the standard sizes of integers, floats, and complex types of both signed and unsigned.
Vectors have a well-defined interface that allows us to make, set, get, and fill them. We can also get the length of a vector with pmt::length.
For standard vectors, these functions look like:
Uniform vectors have the same types of functions, but they are data type-dependent. The following list tries to explain them where you substitute the specific data type prefix for dtype (prefixes being: u8, u16, u32, u64, s8, s16, s32, s64, f32, f64, c32, c64).
Note: We break the contract with vectors. The 'set' functions actually change the data underneath. It is important to keep track of the implications of setting a new value as well as accessing the 'vector_writable_elements' data. Since these are mostly standard data types, sets and gets are atomic, so it is unlikely to cause a great deal of harm. But it's only unlikely, not impossible. Best to use mutexes whenever manipulating data in a vector.
A BLOB is a 'binary large object' type. In PMT's, this is actually just a thin wrapper around a u8vector.
Pairs are inspired by LISP 'cons' data types, so you will find the language here comes from LISP. A pair is just a pair of PMT objects. They are manipulated using the following functions:
It is often important to hide the fact that we are working with PMTs to make them easier to transmit, store, write to file, etc. The PMT library has methods to serialize data into a string buffer or a string and then methods to deserialize the string buffer or string back into a PMT. We use this extensively in the metadata files (see Metadata Information).
For example, we will serialize the data above to make it into a string ready to be written to a file and then deserialize it back to its original PMT.
The line where we 'print ser_str' will print and parts will be readable, but the point of serializing is not to make a human-readable string. This is only done here as a test.
In Python, the repr function of a PMT object is overloaded to call 'pmt::write_string'. This means that any time we call a formatted printing operation on a PMT object, the PMT library will properly format the object for display.
In C++, we can use the 'pmt::print(object)' function or print the contents is using the overloaded "<<" operator with a stream buffer object. In C++, we can inline print the contents of a PMT like:
1.8.6