From 036fa34dee2480530366230e4fdf910f318e2f03 Mon Sep 17 00:00:00 2001 From: christian mueller Date: Tue, 6 Mar 2012 15:28:59 +0100 Subject: * last changes in the documentation --- include/shared/CAmSerializer.h | 131 ++++++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 59 deletions(-) (limited to 'include') diff --git a/include/shared/CAmSerializer.h b/include/shared/CAmSerializer.h index 8a955df..03935f4 100644 --- a/include/shared/CAmSerializer.h +++ b/include/shared/CAmSerializer.h @@ -27,7 +27,10 @@ #include "CAmDltWrapper.h" #include "CAmSocketHandler.h" -//todo: performance improvement we could implement a memory pool that is more efficient here and avoids allocation and deallocation times. +/** + * todo: performance improvement we could implement a memory pool that is more efficient here and avoids + * allocation and deallocation times. + */ namespace am { @@ -36,8 +39,11 @@ namespace am * The constructor must be called within the main threadcontext, after that using the * overloaded template function call will serialize all calls and call them within the * main thread context.\n - * If you want to use synchronous calls make sure that you use one instance of this class - * per thread otherwise you could be lost in never returning calls. + * \warning asynchronous calls may be used in the mainthread context, but if you want to use synchronous calls make sure that you use one + * instance of this class per thread otherwise you could be lost in never returning calls.\n + * Examples of the usage can be found in IAmCommandReceiverShadow of the ControlPlugin or IAmRoutingReceiverShadow of the + * PluginRoutingInterfaceAsync + * */ class CAmSerializer { @@ -269,6 +275,9 @@ private: } }; + /** + * template for synchronous calls with one argument on a const function + */ template class CAmSyncOneArgConstDelegate: public CAmDelegate { private: @@ -343,6 +352,9 @@ private: } }; + /** + * template for synchronous calls with two arguments on a const function + */ template class CAmSyncTwoArgConstDelegate: public CAmDelegate { private: @@ -466,6 +478,9 @@ private: } }; + /** + * delegate template for five arguments + */ template class CAmSyncFiveArgDelegate: public CAmDelegate { private: @@ -511,6 +526,9 @@ private: } }; + /** + * template for synchronous calls with six arguments + */ template class CAmSyncSixArgDelegate: public CAmDelegate { private: @@ -579,7 +597,8 @@ public: * calls a function with no arguments threadsafe * @param instance the instance of the class that shall be called * @param function the function that shall be called as memberfunction pointer. - * Here is an example: + * @tparam TClass1 the type of the Class to be called + * \section ex Example: * @code * class myClass * { @@ -602,7 +621,10 @@ public: * calls a function with one arguments asynchronously threadsafe * @param instance the instance of the class that shall be called * @param function the function that shall be called as memberfunction pointer. - * Here is an example: + * @param argument the argument + * @tparam TClass1 the type of the Class to be called + * @tparam Targ the type of the argument to be called + * \section ex Example: * @code * class myClass * { @@ -613,6 +635,7 @@ public: * myClass instanceMyClass; * serial(&instanceMyClass,&myClass::myfunction,k); * @endcode + * */ template void asyncCall(TClass1* instance, void (TClass1::*function)(Targ), Targ argument) @@ -623,10 +646,13 @@ public: /** * calls a function with two arguments asynchronously threadsafe. for more see asyncCall with one argument - * @param instance - * @param function - * @param argument - * @param argument1 + * @param instance pointer to the instance of the class + * @param function memberfunction poitner + * @param argument the first argument + * @param argument1 the second argument + * @tparam TClass1 the type of the Class to be called + * @tparam Targ the type of the argument to be called + * @tparam Targ1 the type of the first argument to be called */ template void asyncCall(TClass1* instance, void (TClass1::*function)(Targ argument, Targ1 argument1), Targ argument, Targ1 argument1) @@ -636,26 +662,7 @@ public: } /** - * calls a function with three arguments asynchronously threadsafe. for more see asyncCall with one argument - * @param instance - * @param function - * @param argument - * @param argument1 template - void syncCall(TClass1* instance, TretVal(TClass1::*function)(Targ,Targ1), TretVal& retVal, Targ& argument, Targ1& argument1) - { - CAmSyncTwoArgDelegate* p(new CAmSyncTwoArgDelegate(instance, function, argument, argument1)); - send(static_cast(p)); - int numReads; - CAmDelegagePtr ptr; - if ((numReads=read(mReturnPipe[0],&ptr, sizeof(ptr))) == -1) - { - logError("CAmSerializer::receiverCallback could not read pipe!"); - throw std::runtime_error("CAmSerializer Could not read pipe!"); - } - //working with friend class here is not the finest of all programming stiles but it works... - retVal=p->returnResults(argument,argument1); - } - * @param argument2 + * calls a function with three arguments asynchronously threadsafe. for more see other asycCall */ template void asyncCall(TClass1* instance, void (TClass1::*function)(Targ argument, Targ1 argument1, Targ2 argument2), Targ argument, Targ1 argument1, Targ2 argument2) @@ -665,13 +672,7 @@ public: } /** - * calls a function with four arguments asynchronously threadsafe. for more see asyncCall with one argument - * @param instance - * @param function - * @param argument - * @param argument1 - * @param argument2 - * @param argument3 + * calls a function with four arguments asynchronously threadsafe. for more see other asycCall */ template void asyncCall(TClass1* instance, void (TClass1::*function)(Targ argument, Targ1 argument1, Targ2 argument2, Targ3 argument3), Targ argument, Targ1 argument1, Targ2 argument2, Targ3 argument3) @@ -684,7 +685,10 @@ public: * calls a synchronous function with no arguments threadsafe * @param instance the instance of the class that shall be called * @param function the function that shall be called as memberfunction pointer. - * Here is an example: + * @param retVal the return parameter, no const allowed ! + * @tparam TClass1 the type of the class to be called + * @tparam TretVal the type of the return parameter + * \section ex Example: * @code * class myClass * { @@ -720,7 +724,14 @@ public: * calls a function with one argument synchronous threadsafe * @param instance the instance of the class that shall be called * @param function the function that shall be called as memberfunction pointer. - * Here is an example: + * @param retVal the return parameter, no const allowed ! + * @param argument the argument, no const allowed ! + * @tparam TClass1 the type of the class to be called + * @tparam TretVal the type of the return parameter + * @tparam TargCall the type of the argument like in the function to be called. here all references and const must be + * respected! + * @tparam Targ the type of the argument, here no const and no references allowed ! + * \section ex Example: * @code * class myClass * { @@ -752,6 +763,9 @@ public: delete p; } + /** + * calls a function with one argument synchronous threadsafe for const functions. For more see syncCall with one argument + */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall) const, TretVal& retVal, Targ& argument) { @@ -770,12 +784,7 @@ public: } /** - * calls a function with two arguments synchronously threadsafe. for more see syncCall with one argument - * @param instance - * @param function - * @param retVal - * @param argument - * @param argument1 + * calls a function with two arguments synchronously threadsafe. For more see syncCall with one argument */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall, Targ1Call), TretVal& retVal, Targ& argument, Targ1& argument1) @@ -792,7 +801,9 @@ public: retVal = p->returnResults(argument, argument1); delete p; } - + /** + * calls a function with two arguments synchronously threadsafe const. For more see syncCall with one argument + */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall, Targ1Call) const, TretVal& retVal, Targ& argument, Targ1& argument1) { @@ -811,12 +822,6 @@ public: /** * calls a function with three arguments synchronously threadsafe. for more see syncCall with one argument - * @param instance - * @param function - * @param retVal - * @param argument - * @param argument1 - * @param argument2 */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall, TargCall1, TargCall2), TretVal& retVal, Targ& argument, Targ1& argument1, Targ2& argument2) @@ -837,13 +842,6 @@ public: /** * calls a function with four arguments synchronously threadsafe. for more see syncCall with one argument - * @param instance - * @param function - * @param retVal - * @param argument - * @param argument1 - * @param argument2 - * @param argument3 */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall, TargCall1, TargCall2, TargCall3), TretVal& retVal, Targ& argument, Targ1& argument1, Targ2& argument2, Targ3& argument3) @@ -862,6 +860,9 @@ public: delete p; } + /** + * calls a function with five arguments synchronously threadsafe. for more see syncCall with one argument + */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall, TargCall1, TargCall2, TargCall3, TargCall4), TretVal& retVal, Targ& argument, Targ1& argument1, Targ2& argument2, Targ3& argument3, Targ4& argument4) { @@ -879,6 +880,9 @@ public: delete p; } + /** + * calls a function with six arguments synchronously threadsafe. for more see syncCall with one argument + */ template void syncCall(TClass1* instance, TretVal (TClass1::*function)(TargCall, TargCall1, TargCall2, TargCall3, TargCall4, TargCall5), TretVal& retVal, Targ& argument, Targ1& argument1, Targ2& argument2, Targ3& argument3, Targ4& argument4, Targ5& argument5) { @@ -896,6 +900,9 @@ public: delete p; } + /** + * receiver callback for sockethandling, for more, see CAmSocketHandler + */ void receiverCallback(const pollfd pollfd, const sh_pollHandle_t handle, void* userData) { (void) handle; @@ -910,6 +917,9 @@ public: mListDelegatePoiters.assign(listPointers, listPointers + (numReads / sizeof(CAmDelegagePtr))); } + /** + * checker callback for sockethandling, for more, see CAmSocketHandler + */ bool checkerCallback(const sh_pollHandle_t handle, void* userData) { (void) handle; @@ -919,6 +929,9 @@ public: return (true); } + /** + * dispatcher callback for sockethandling, for more, see CAmSocketHandler + */ bool dispatcherCallback(const sh_pollHandle_t handle, void* userData) { (void) handle; @@ -938,7 +951,7 @@ public: /** * The constructor must be called in the mainthread context ! - * @param iSocketHandler pointer to the sockethandler + * @param iSocketHandler pointer to the CAmSocketHandler */ CAmSerializer(CAmSocketHandler *iSocketHandler) : mPipe(), // -- cgit v1.2.1