Blockfactory
The block factory allows users to register custom IP into the framework. Registering blocks into the factory system is easy and the benefits are massive. See code examples in the code guide: https://github.com/guruofquality/gras/wiki/Codeguide#wiki-block-factory
For documentation on building and installing custom IP into the framework: https://github.com/guruofquality/gras/wiki/Moduleguide
Table of Contents
The API to register factories and methods is incredibly clean; as is the API to use factories and to factories and methods. Registering a block factory or a class method takes one line of code. Users do not need to declare uncessary template arguments, ugly function binds, or messy polymorphic casts. GRAS handles the dirty-work so users code can be clean and simple.
Calling into a registered class method is guaranteed to be thread safe. When calling into the registered method, the call cannot overlap with the execution of the work function or other registered methods. Users do not need to sprinkle thread mutexes throughout the code.
The framework handles all of the translation into Python, so users never have to. That means users do not need SWIG. Just write your blocks in C++, register the calls, and your block is now available in Python. This means users write the minimal amount of code, compiles are fast and easy, and compiler errors are easier to fix.
This registration interface allows blocks to be treated as opaque: Meaning, blocks do not need to expose public member functions to give client code full access to their public methods. Therefore, blocks do not need to expose any public headers because all methods can be dealt with through the callable interface.
This may sound trivial, but it allows a power new feature, where blocks can access other blocks in the topology through the element tree for control and configuration purposes. Read more about element tree and zeroconf here:
Its a stict requirement that all input arguments for factory registerations and registered class methods be const references (as in const type &arg). This means that input arguments are readonly, no pointers or references. If the user needed an input argument to be read-write, they should find a way to solve this using return parameters instead.
Any data type can be passed into a registered call or returned. However, only primitives and stl types are available by default for use with Python. This means integers, strings, vectors are supported; but MyCustomType may not be. The good news is that arbitrary types can be registered into the type system.
An example of this can be found in the grex/uhd subdirectory:
Documentation for type registration:
Often, users put documentation inside public headers in the form of doxygen markup. The documentation is later extracted with Doxygen and turned into html. While using the factory doesn't really prevent this kind of documentation, users may feel that its easier to simply not create public headers. Should that be the case, what about possible documentation alternatives? Here are two suggestions:
- Put documentation inside the GRC XML <doc> tag
- Put useful documentation on the project wiki page