Feature #907

API Abstraction Layer

Added by Rogers, Chris over 9 years ago. Updated almost 9 years ago.

Richards, Alexander
Target version:
Start date:
15 February 2012
Due date:
% Done:


Estimated time:
In Development


We need to define the abstraction layer for the MAUS API. My scappy notes from discussion yesterday:

Interface classes

Cpp Interface classes
Make a new folder called src/common_cpp/API

Template interface classes like

  • IInput
  • IReduce
  • IOutput
  • IMap

for template class T
IInput<T> defines

bool birth(std::string)
bool death()
T emitter()

IReduce<T> defines

bool birth(std::string)
bool death()
T process(T)

IMap<T> defines

bool birth(std::string)
bool death()
T process(T) const

The reason for the const-ness of this function is that we parallelise on this function, so different process() calls shouldn't alter internal member data - really this function is being called on another machine somewhere far away, so parallel process(), and the main() function can't see any data being edited. Don't know how we enforce this in python, maybe there is an appropriate function decorator?

IOutput<T> defines

bool birth(std::string)
bool death()
bool save(T)

Python Interface classes

As above but done in Python, in src/common_py/API

Base class

Base class with some error handling for each of the Interfaces defined above - should catch exceptions using the model

my_function(args) {
try {
} catch(Squeal & squeal) {
    CppErrorHandler::getInstance()->HandleSquealNoJson(squee, _classname);
} catch (std::exception) {
    CppErrorHandler::getInstance()->HandleSquealNoJson(std::exception, _classname);
} catch (...) {

std::string _classname - protected base class member

T map::process(T) {
try {
} catch(Squeal & squeal) {
CppErrorHandler::getInstance()->HandleSqueal(T spill, Squeal exc, _classname);
} catch (std::exception) {
CppErrorHandler::getInstance()->HandleSqueal(T spill, std::exception exc, _classname);
} catch (...) {


Then edit CppErrorHandler to make HandleSqueal a template function. Overload for T is a Json::Value and call as before. If T is not a Json::Value, call HandleSquealNoJson(...)

API Documentation

Make a latex file that explains the API, say doc/doc_src/api.tex - may be a Rogers task.


Updated by Rogers, Chris over 9 years ago

  • Assignee changed from Rogers, Chris to Richards, Alexander

Amusing aside - this got blocked by IT security stuff, presumably for all the death and child references...


Updated by Rogers, Chris about 9 years ago

Code review - in general, looks again like very nice quality code. Some comments:

  • Your define statements e.g. #ifndef _MAUS_API_EXCEPTIONS should have the path in like #ifndef _SRC_COMMON_CPP_API_APIEXCEPTION_
  • For the exceptions, could you explain in Doxygen what each exception is?
  • Could you make some common MAUS base exception class like MAUSException. Doesn't have to have much content, but one could imagine porting over e.g. the stack trace functionality from Squeak?
  • include should give the full path like #include "src/common_cpp/API/IModule.hh"
  • In MapBase.hh #include "json/json.h" best to put third party #includes after C++, C includes before MAUS includes
  • In your MapBase, InputBase, etc - I sort of have an irrational bias against multiple inheritance but I can't see a better way of doing it...
  • Why do you have two "public:" declarations in all of your Base classes? One for public functions which should be overloaded?
  • Can you put some more comments in please. e.g. it wasn't obvious to me how MapBase should be used - e.g. what's the difference between process(INPUT*) and process(OUTPUT*)? Also needs an addition to the maus latex files in doc/doc_src (see output here).
  • Json converters - looks like you comment out some stuff - I think the old reverse conversion (which is now in a different class). Can you just delete it rather than commenting?
  • Did you mean to commit the example in src/common_py/API/
  • src/common_py/API/ - Looks like fun but I have no idea what it does :) I guess this is for the const decorator.
  • Did you mean to commit src/common_py/API/ (Should probably be an integration test or something)

I haven't checked your tests or test coverage... I will have a look after the merge.


Updated by Rogers, Chris about 9 years ago

  • Workflow changed from New Issue to In Development

Updated by Rogers, Chris about 9 years ago

Email from Alex:

Thanks for the code comments, I havent yet finished reading them but I should just point out that in terms of readability and commenting up the MapBase class in particular this was something that I have just found that I had omitted owing to it's complexity and wanting to simplify them all with a specific -inl.hh file. I had already been doing it this morning actually . Please could you let me commit the changes that I have done and then tell me if it goes someway to answering the problems you had in this regard. 

Updated by Rogers, Chris about 9 years ago

I reread the MapBase.hh not in a browser and it makes more sense to me - user overloads _process function and then MapBase tries to call the appropriate converter.


Updated by Richards, Alexander about 9 years ago

Yup bingo that's it.


Updated by Rogers, Chris about 9 years ago

I think this is closed once you add some documentation... do you think you could get that done in the next few days?


Updated by Rogers, Chris about 9 years ago

Or would you rather I do it?


Updated by Richards, Alexander about 9 years ago

Hi Chris,
I've started throwing a little something together. I'll email you it. When done feel free to edit/add to it.



Updated by Rogers, Chris almost 9 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

Updated by Rogers, Chris almost 9 years ago

  • Target version changed from Future MAUS release to MAUS-v0.4.0

Also available in: Atom PDF