Feature #907
API Abstraction Layer
100%
Description
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 {
child_function_call
} 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
EXCEPT
T map::process(T) {
try {
child_function_call
} 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 almost 12 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 over 11 years ago
Code review - in general, looks again like very nice quality code. Some comments:
- Your define statements e.g.
#ifndef _MAUS_API_EXCEPTIONSshould 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/Constable.py?
- src/common_py/API/DecoratorUtils.py - 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/main.py? (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 over 11 years ago
FYI I made a test build at http://test.mice.rl.ac.uk/job/MAUS_richards_api/
Updated by Rogers, Chris over 11 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 over 11 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 Rogers, Chris over 11 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 Richards, Alexander over 11 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.
Cheers
Alex
Updated by Rogers, Chris about 11 years ago
- Status changed from Open to Closed
- % Done changed from 0 to 100
Updated by Rogers, Chris about 11 years ago
- Target version changed from Future MAUS release to MAUS-v0.4.0