diff options
Diffstat (limited to 'TAO')
72 files changed, 3257 insertions, 3609 deletions
diff --git a/TAO/ChangeLogs/ChangeLog-02a b/TAO/ChangeLogs/ChangeLog-02a index cb983fab6d3..da2dc7bbc97 100644 --- a/TAO/ChangeLogs/ChangeLog-02a +++ b/TAO/ChangeLogs/ChangeLog-02a @@ -1,3 +1,87 @@ +Mon Oct 30 18:51:02 2000 Carlos O'Ryan <coryan@uci.edu> + + * orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.cpp: + * orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.cpp: + * orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.cpp: + * orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.cpp: + Sun/CC 5.1 Patch 109490-01 gives errors if the formal arguments + names in a template definition do not match the names in the + declaration. + Fixed the problems in the ESF directory per J. Russell + Noseworthy <rnosewor@objectsciences.com> report. + This is a partial fix for [BUGID:709] + + * orbsvcs/orbsvcs/ESF/ESF_Busy_Lock.h: + * orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.h: + * orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.h: + * orbsvcs/orbsvcs/ESF/ESF_Defaults.h: + * orbsvcs/orbsvcs/ESF/ESF_Delayed_Changes.h: + * orbsvcs/orbsvcs/ESF/ESF_Delayed_Command.h: + * orbsvcs/orbsvcs/ESF/ESF_Immediate_Changes.h: + * orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.h: + * orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.i: + * orbsvcs/orbsvcs/ESF/ESF_Peer_Workers.h: + * orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.h: + * orbsvcs/orbsvcs/ESF/ESF_Proxy_Collection.h: + * orbsvcs/orbsvcs/ESF/ESF_Proxy_List.h: + * orbsvcs/orbsvcs/ESF/ESF_Proxy_RB_Tree.h: + * orbsvcs/orbsvcs/ESF/ESF_Proxy_RefCount_Guard.h: + * orbsvcs/orbsvcs/ESF/ESF_RefCount_Guard.h: + * orbsvcs/orbsvcs/ESF/ESF_Shutdown_Proxy.h: + * orbsvcs/orbsvcs/ESF/ESF_Worker.h: + * orbsvcs/orbsvcs/Event/EC_And_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Basic_Factory.h: + * orbsvcs/orbsvcs/Event/EC_Basic_Filter_Builder.h: + * orbsvcs/orbsvcs/Event/EC_Bitmask_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Busy_Lock.h: + * orbsvcs/orbsvcs/Event/EC_Conjunction_Filter.h: + * orbsvcs/orbsvcs/Event/EC_ConsumerAdmin.h: + * orbsvcs/orbsvcs/Event/EC_ConsumerControl.h: + * orbsvcs/orbsvcs/Event/EC_Default_Factory.h: + * orbsvcs/orbsvcs/Event/EC_Defaults.h: + * orbsvcs/orbsvcs/Event/EC_Disjunction_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Dispatching.h: + * orbsvcs/orbsvcs/Event/EC_Dispatching_Task.h: + * orbsvcs/orbsvcs/Event/EC_Event_Channel.h: + * orbsvcs/orbsvcs/Event/EC_Factory.h: + * orbsvcs/orbsvcs/Event/EC_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Filter_Builder.h: + * orbsvcs/orbsvcs/Event/EC_Gateway.h: + * orbsvcs/orbsvcs/Event/EC_Gateway_Sched.h: + * orbsvcs/orbsvcs/Event/EC_Gateway_UDP.h: + * orbsvcs/orbsvcs/Event/EC_MT_Dispatching.h: + * orbsvcs/orbsvcs/Event/EC_Masked_Type_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Negation_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Null_Factory.h: + * orbsvcs/orbsvcs/Event/EC_Null_Scheduling.h: + * orbsvcs/orbsvcs/Event/EC_ObserverStrategy.h: + * orbsvcs/orbsvcs/Event/EC_Per_Supplier_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Prefix_Filter_Builder.h: + * orbsvcs/orbsvcs/Event/EC_Priority_Dispatching.h: + * orbsvcs/orbsvcs/Event/EC_Priority_Scheduling.h: + * orbsvcs/orbsvcs/Event/EC_ProxyConsumer.h: + * orbsvcs/orbsvcs/Event/EC_ProxySupplier.h: + * orbsvcs/orbsvcs/Event/EC_QOS_Info.h: + * orbsvcs/orbsvcs/Event/EC_Reactive_ConsumerControl.h: + * orbsvcs/orbsvcs/Event/EC_Reactive_SupplierControl.h: + * orbsvcs/orbsvcs/Event/EC_Reactive_Timeout_Generator.h: + * orbsvcs/orbsvcs/Event/EC_Sched_Factory.h: + * orbsvcs/orbsvcs/Event/EC_Sched_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Sched_Filter_Builder.h: + * orbsvcs/orbsvcs/Event/EC_Scheduling_Strategy.h: + * orbsvcs/orbsvcs/Event/EC_SupplierAdmin.h: + * orbsvcs/orbsvcs/Event/EC_SupplierControl.h: + * orbsvcs/orbsvcs/Event/EC_Supplier_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Supplier_Filter_Builder.h: + * orbsvcs/orbsvcs/Event/EC_Timeout_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Timeout_Generator.h: + * orbsvcs/orbsvcs/Event/EC_Trivial_Supplier_Filter.h: + * orbsvcs/orbsvcs/Event/EC_Type_Filter.h: + * orbsvcs/orbsvcs/Event/EC_UDP_Admin.h: + Update all the header files to use Doxygen style documentation. + I used Darrell's doxygen-convert.pl script and a little + hand-crafting. + Mon Oct 30 18:35:46 2000 Darrell Brunsch <brunsch@uci.edu> * examples/POA/Forwarding/Servant_Activator.cpp: @@ -15,191 +99,191 @@ Mon Oct 30 18:35:46 2000 Darrell Brunsch <brunsch@uci.edu> Mon Oct 30 17:47:13 2000 Priyanka Gontla <pgontla@ece.uci.edu> - * tao/Policy_Manager.h: - * tao/Policy_Manager.cpp (TAO_Policy_Manager_Impl): - Changed the type of relative_roundtrip_timeout_ and sync_scope_ to - CORBA::Policy *. - Hence instead of calling TAO_RelativeTimeoutPolicy::clone or - TAO_Sync_Scope_Policy::clone, calling CORBA::Policy::copy. - Made related changes. - - Modify the return parameter for - relative_roundtrip_timeout () and sync_scope () to - CORBA::Policy_ptr in all the classes in the file. - - * tao/ORB_Core.h : - * tao/ORB_Core.cpp: - Declare and define TAO_ORB_Core::call_timeout_hook, - TAO_ORB_Core::set_timeout_hook, - TAO_ORB_Core::call_sync_scope_hook, - TAO_ORB_Core::set_sync_scope_hook which are used to call the - hooks to set and get the values of timeout/scope and save the - hook for the respective policies so that they can be used later - in need. - - Also, get_sync_strategy is defined as a helper to get the - TAO_Sync_Strategy related to the Sync_Scope passed to it. - - The function TAO_ORB_Core::stubless_sync_scope helps get the - scope when the stub is nil. - - Modify the return parameter for - TAO_ORB_Core::relative_roundtrip_timeout (), - TAO_ORB_Core::default_relative_roundtrip_timeout (), - TAO_ORB_Core::stubless_relative_roundtrip_timeout (), - TAO_ORB_Core::default_sync_scope () and - TAO_ORB_Core::sync_scope () to CORBA::Policy_ptr. - - The same change recursively in all the classes which call these - functions. - - * tao/Stub.h: - * tao/Stub.cpp (sync_scope): - Modified TAO_Stub::sync_strategy () to call - TAO_ORB_Core::call_sync_scope_hook to get the scope value. - This scope value is passed to TAO_ORB_Core::get_sync_strategy () - to get the TAO_Sync_Strategy. - - Modify the return parameter for - TAO_ORB_Core::relative_roundtrip_timeout (), - TAO_ORB_Core::sync_scope () to CORBA::Policy_ptr. - - Modified TAO::Sync_scope to call - TAO_ORB_Core::stubless_sync_scope to avoid code repetition. - - * tao/Messaging_Policy_i.h (SyncScopePolicy,): - * tao/Messaging_Policy_i.cpp: - Declare and define TAO_RelativeRoundtripTimeoutPolicy::hook - and TAO_Sync_Scope_Policy::hook functions. The - functions are called to set the hooks for the respective policies - to indicate that the policies are set and also to know the Timeout - and scope values in the respective cases. - - * tao/Messaging_PolicyFactory.cpp (create_policy): - Remove the if-defs for TAO_HAS_RELATIVE_ROUNDTRIP_TIMEOUT_POLICY - and TAO_HAS_SYNC_SCOPE_POLICY in the switch-case block. - - * tao/Messaging_ORBInitializer.cpp: - Save the pointers to hooks for - TAO_RelativeRoundtripTimeout and TAO_Sync_Scope - policies in the - TAO_Messaging_ORBInitializer::pre_init by calling the - TAO_ORB_Core::set_timeout_hook and - TAO_ORB_Core::set_sync_scope_hook. - - * tao/UIOP_Connect.h: - * tao/UIOP_Connect.cpp: - - * tao/SHMIOP_Connect.h: - * tao/SHMIOP_Connect.cpp (handle_timeout): - - * tao/IIOP_Connect.h: - * tao/IIOP_Connect.cpp (handle_timeout): - Set the timeout value by calling TAO_ORB_Core::call_timeout_hook - instead of getting a TAO_RelativeRoundtripPolicy pointer and - proceeding from there. - - * tao/Invocation.h: - * tao/Invocation.cpp: - Same as IIOP_Connect for TAO_RelativeRoundtripTimeoutPolicy. - Similar change with sync_scope. Instead of getting a - TAO_Sync_Scope_Policy_ptr and gettting the sync_scope - value, call the hook for the sync_scope which is - TAO_ORB_Core::call_sync_scope_hook. - - * tao/ClientRequestInfo.h : - * tao/ClientRequestInfo.cpp (sync_scope): - Modified the return value of sync_scope from - Messaging::SyncScope to CORBA::Short. + * tao/Policy_Manager.h: + * tao/Policy_Manager.cpp (TAO_Policy_Manager_Impl): + Changed the type of relative_roundtrip_timeout_ and sync_scope_ to + CORBA::Policy *. + Hence instead of calling TAO_RelativeTimeoutPolicy::clone or + TAO_Sync_Scope_Policy::clone, calling CORBA::Policy::copy. + Made related changes. + + Modify the return parameter for + relative_roundtrip_timeout () and sync_scope () to + CORBA::Policy_ptr in all the classes in the file. + + * tao/ORB_Core.h : + * tao/ORB_Core.cpp: + Declare and define TAO_ORB_Core::call_timeout_hook, + TAO_ORB_Core::set_timeout_hook, + TAO_ORB_Core::call_sync_scope_hook, + TAO_ORB_Core::set_sync_scope_hook which are used to call the + hooks to set and get the values of timeout/scope and save the + hook for the respective policies so that they can be used later + in need. + + Also, get_sync_strategy is defined as a helper to get the + TAO_Sync_Strategy related to the Sync_Scope passed to it. + + The function TAO_ORB_Core::stubless_sync_scope helps get the + scope when the stub is nil. + + Modify the return parameter for + TAO_ORB_Core::relative_roundtrip_timeout (), + TAO_ORB_Core::default_relative_roundtrip_timeout (), + TAO_ORB_Core::stubless_relative_roundtrip_timeout (), + TAO_ORB_Core::default_sync_scope () and + TAO_ORB_Core::sync_scope () to CORBA::Policy_ptr. + + The same change recursively in all the classes which call these + functions. + + * tao/Stub.h: + * tao/Stub.cpp (sync_scope): + Modified TAO_Stub::sync_strategy () to call + TAO_ORB_Core::call_sync_scope_hook to get the scope value. + This scope value is passed to TAO_ORB_Core::get_sync_strategy () + to get the TAO_Sync_Strategy. + + Modify the return parameter for + TAO_ORB_Core::relative_roundtrip_timeout (), + TAO_ORB_Core::sync_scope () to CORBA::Policy_ptr. + + Modified TAO::Sync_scope to call + TAO_ORB_Core::stubless_sync_scope to avoid code repetition. + + * tao/Messaging_Policy_i.h (SyncScopePolicy,): + * tao/Messaging_Policy_i.cpp: + Declare and define TAO_RelativeRoundtripTimeoutPolicy::hook + and TAO_Sync_Scope_Policy::hook functions. The + functions are called to set the hooks for the respective policies + to indicate that the policies are set and also to know the Timeout + and scope values in the respective cases. + + * tao/Messaging_PolicyFactory.cpp (create_policy): + Remove the if-defs for TAO_HAS_RELATIVE_ROUNDTRIP_TIMEOUT_POLICY + and TAO_HAS_SYNC_SCOPE_POLICY in the switch-case block. + + * tao/Messaging_ORBInitializer.cpp: + Save the pointers to hooks for + TAO_RelativeRoundtripTimeout and TAO_Sync_Scope + policies in the + TAO_Messaging_ORBInitializer::pre_init by calling the + TAO_ORB_Core::set_timeout_hook and + TAO_ORB_Core::set_sync_scope_hook. + + * tao/UIOP_Connect.h: + * tao/UIOP_Connect.cpp: + + * tao/SHMIOP_Connect.h: + * tao/SHMIOP_Connect.cpp (handle_timeout): + + * tao/IIOP_Connect.h: + * tao/IIOP_Connect.cpp (handle_timeout): + Set the timeout value by calling TAO_ORB_Core::call_timeout_hook + instead of getting a TAO_RelativeRoundtripPolicy pointer and + proceeding from there. + + * tao/Invocation.h: + * tao/Invocation.cpp: + Same as IIOP_Connect for TAO_RelativeRoundtripTimeoutPolicy. + Similar change with sync_scope. Instead of getting a + TAO_Sync_Scope_Policy_ptr and gettting the sync_scope + value, call the hook for the sync_scope which is + TAO_ORB_Core::call_sync_scope_hook. + + * tao/ClientRequestInfo.h : + * tao/ClientRequestInfo.cpp (sync_scope): + Modified the return value of sync_scope from + Messaging::SyncScope to CORBA::Short. Mon Oct 30 18:57:22 2000 Irfan Pyarali <irfan@cs.wustl.edu> - * tao/PortableServer/POA: Removed the Forwarding Servant. The - forwarding servant was ill-constructed: (a) it threw exceptions - the incorrect way since the correct way is to call - set_exception() on the ServerRequest and not to throw an - exception; (b) the forward_object() method on the POA leads to - deadlock if called from an upcall on the object being forwarded; - (c) Servant Managers is the only correct way to forward requests - - Default Servants is not the correct solution. - - * tao/PortableServer/Object_Adapter.cpp (dispatch, - dispatch_servant, and prepare_for_upcall): Changed these methods - such that the forwarding exception can only be raised by the - servant managers. Now the forward exception is caught in - prepare_for_upcall() when we are looking for the servant and may - potentially call the servant managers. If this exception is - raised by a regular servant or by a default servant, the - exception is reported to the client as an unknown exception. - Thanks to Ossama for reporting this problem. This fix closes - bug 690. - - * Since the signature of - TAO_Object_Adapter::Servant_Upcall::prepare_for_upcall() got - changed because of the above fix, it required a change to - collocation code that performs through POA calls. The following - files were effected: - - - tao/PortableServer/Collocated_Object.cpp - - tao/PortableServer/DomainS.cpp - - tao/PortableServer/ImplRepoS.cpp - - tao/PortableServer/MessagingS.cpp - - tao/PortableServer/PolicyS.cpp - - tao/PortableServer/ThruPOA_Object_Proxy_Impl.cpp - - and - - - TAO_IDL/be/be_visitor_interface/thru_poa_collocated_ss.cpp - - TAO_IDL/be/be_visitor_operation/thru_poa_collocated_ss.cpp - - * tao/Adapter.h (TAO_Adapter): Added a new return value for failed - dispatching of upcalls. + * tao/PortableServer/POA: Removed the Forwarding Servant. The + forwarding servant was ill-constructed: (a) it threw exceptions + the incorrect way since the correct way is to call + set_exception() on the ServerRequest and not to throw an + exception; (b) the forward_object() method on the POA leads to + deadlock if called from an upcall on the object being forwarded; + (c) Servant Managers is the only correct way to forward requests + - Default Servants is not the correct solution. + + * tao/PortableServer/Object_Adapter.cpp (dispatch, + dispatch_servant, and prepare_for_upcall): Changed these methods + such that the forwarding exception can only be raised by the + servant managers. Now the forward exception is caught in + prepare_for_upcall() when we are looking for the servant and may + potentially call the servant managers. If this exception is + raised by a regular servant or by a default servant, the + exception is reported to the client as an unknown exception. + Thanks to Ossama for reporting this problem. This fix closes + bug 690. + + * Since the signature of + TAO_Object_Adapter::Servant_Upcall::prepare_for_upcall() got + changed because of the above fix, it required a change to + collocation code that performs through POA calls. The following + files were effected: + + - tao/PortableServer/Collocated_Object.cpp + - tao/PortableServer/DomainS.cpp + - tao/PortableServer/ImplRepoS.cpp + - tao/PortableServer/MessagingS.cpp + - tao/PortableServer/PolicyS.cpp + - tao/PortableServer/ThruPOA_Object_Proxy_Impl.cpp + + and + + - TAO_IDL/be/be_visitor_interface/thru_poa_collocated_ss.cpp + - TAO_IDL/be/be_visitor_operation/thru_poa_collocated_ss.cpp + + * tao/Adapter.h (TAO_Adapter): Added a new return value for failed + dispatching of upcalls. Mon Oct 30 18:38:42 2000 Jeff Parsons <parsons@cs.wustl.edu> - * TAO_IDL/driver/drv_preproc.cpp: + * TAO_IDL/driver/drv_preproc.cpp: - Plugged a memory leak by removing an extra string copy - when adding the include path for orb.idl to the - command line arglist. + Plugged a memory leak by removing an extra string copy + when adding the include path for orb.idl to the + command line arglist. - * TAO_IDL/util/utl_scope.cpp: + * TAO_IDL/util/utl_scope.cpp: - Found a missing 'delete' for an iterator that was - created on the heap. Instead of adding the 'delete', - just created the iterator on the stack. + Found a missing 'delete' for an iterator that was + created on the heap. Instead of adding the 'delete', + just created the iterator on the stack. Mon Oct 30 10:40:57 2000 Priyanka Gontla <pgontla@ece.uci.edu> - * docs/tutorials/Quoter/AMI/Makefile: - Updated the Makefile to link lTAO_PortableServer. Thanks to - Walt Corey <wcorey@ibm.net> for reporting the bug. + * docs/tutorials/Quoter/AMI/Makefile: + Updated the Makefile to link lTAO_PortableServer. Thanks to + Walt Corey <wcorey@ibm.net> for reporting the bug. Mon Oct 30 15:21:24 2000 Jeff Parsons <parsons@cs.wustl.edu> - * tao/Typecode.cpp: + * tao/Typecode.cpp: - Added a check for a null typecode pointer argument to a function - common to equal() and equivalent(). This change will cause all - Any extractions to fail if the application has not initialized - an ORB. Thanks to Albert Wijnja <albert.wijnja@meco.nl> for - reporting this bug. + Added a check for a null typecode pointer argument to a function + common to equal() and equivalent(). This change will cause all + Any extractions to fail if the application has not initialized + an ORB. Thanks to Albert Wijnja <albert.wijnja@meco.nl> for + reporting this bug. Mon Oct 30 15:00:30 2000 Jeff Parsons <parsons@cs.wustl.edu> - * TAO_IDL/ast/ast_interface.cpp: - * TAO_IDL/fe/fe_interface_header.cpp: + * TAO_IDL/ast/ast_interface.cpp: + * TAO_IDL/fe/fe_interface_header.cpp: - Modified redefinition of forward declared interface - to handle the case where an interface is defined in - a reopening of the module where it is forward declared, - then referenced in a different module. Thanks to - Vsevolod Novikov <novikov@df.nnov.rfnet.ru> for reporting - this bug and sending in an example IDL file. + Modified redefinition of forward declared interface + to handle the case where an interface is defined in + a reopening of the module where it is forward declared, + then referenced in a different module. Thanks to + Vsevolod Novikov <novikov@df.nnov.rfnet.ru> for reporting + this bug and sending in an example IDL file. - * tests/IDL_Test/reopened_modules.idl: + * tests/IDL_Test/reopened_modules.idl: - Added the above example to IDL_Test. + Added the above example to IDL_Test. Mon Oct 30 12:04:18 2000 Carlos O'Ryan <coryan@uci.edu> @@ -208,14 +292,14 @@ Mon Oct 30 12:04:18 2000 Carlos O'Ryan <coryan@uci.edu> Mon Oct 30 12:29:33 2000 Jeff Parsons <parsons@cs.wustl.edu> - * TAO_IDL/be/be_visitor_argument/request_info_arglist.cpp: - * TAO_IDL/be/be_visitor_argument/request_info_sh.cpp: + * TAO_IDL/be/be_visitor_argument/request_info_arglist.cpp: + * TAO_IDL/be/be_visitor_argument/request_info_sh.cpp: - Made the signatures of wstring members and wstring - parameters in constructor signature agree for the - generated TAO_ServerRequest_Info subclasses. Thanks to - Johnny Willemsen <johnny.willemsen@meco.nl> for reporting - this bug. + Made the signatures of wstring members and wstring + parameters in constructor signature agree for the + generated TAO_ServerRequest_Info subclasses. Thanks to + Johnny Willemsen <johnny.willemsen@meco.nl> for reporting + this bug. Sat Oct 28 17:55:29 2000 Carlos O'Ryan <coryan@uci.edu> diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Busy_Lock.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Busy_Lock.h index dc102a2cd69..611013f8959 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Busy_Lock.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Busy_Lock.h @@ -1,18 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Busy_Lock -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// ============================================================================ +/** + * @file ESF_Busy_Lock.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_BUSY_LOCK_H #define TAO_ESF_BUSY_LOCK_H @@ -23,12 +18,30 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/// Adapt classes that implement the "busy lock" protocol, to conform +/// to the ACE Lock interface. +/** + * The ACE Lock interface allows us to use any mutex-like object with + * the ACE synchronization components (such as guards, Lock_Adapter, + * etc.). + * One of the synchronization protocols used in the event services + * uses the following protocol: + * <UL> + * <LI> To acquire the lock the @param busy method of the object is + * invoked. + * <LI> To release the lock the @param idle method of the object is + * invoked. + * <LI> Any changes performed while the lock is held are delayed until + * all the locks are released, i.e. the last call to @param idle + * executes the changes. + * </UL> + */ template<class Adaptee> class TAO_ESF_Busy_Lock_Adapter { public: + /// Constructor TAO_ESF_Busy_Lock_Adapter (Adaptee* adaptee); - // Constructor // = The ACE_Lock methods, please check $ACE_ROOT/ace/Synch.h for // details. diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.cpp b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.cpp index e33d420177f..64558ca1c3f 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.cpp +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.cpp @@ -78,43 +78,43 @@ TAO_ESF_Copy_On_Read<PROXY,COLLECTION,ITERATOR,ACE_LOCK>:: ACE_ENDTRY; } -template<class PROXY, class C, class I, class L> void -TAO_ESF_Copy_On_Read<PROXY,C,I,L>:: +template<class PROXY, class COLLECTION, class ITERATOR, class ACE_LOCK> void +TAO_ESF_Copy_On_Read<PROXY,COLLECTION,ITERATOR,ACE_LOCK>:: connected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) { - ACE_GUARD (L, ace_mon, this->lock_); + ACE_GUARD (ACE_LOCK, ace_mon, this->lock_); proxy->_incr_refcnt (); this->collection_.connected (proxy, ACE_TRY_ENV); } -template<class PROXY, class C, class I, class L> void -TAO_ESF_Copy_On_Read<PROXY,C,I,L>:: +template<class PROXY, class COLLECTION, class ITERATOR, class ACE_LOCK> void +TAO_ESF_Copy_On_Read<PROXY,COLLECTION,ITERATOR,ACE_LOCK>:: reconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) { - ACE_GUARD (L, ace_mon, this->lock_); + ACE_GUARD (ACE_LOCK, ace_mon, this->lock_); proxy->_incr_refcnt (); this->collection_.reconnected (proxy, ACE_TRY_ENV); } -template<class PROXY, class C, class I, class L> void -TAO_ESF_Copy_On_Read<PROXY,C,I,L>:: +template<class PROXY, class COLLECTION, class ITERATOR, class ACE_LOCK> void +TAO_ESF_Copy_On_Read<PROXY,COLLECTION,ITERATOR,ACE_LOCK>:: disconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) { - ACE_GUARD (L, ace_mon, this->lock_); + ACE_GUARD (ACE_LOCK, ace_mon, this->lock_); this->collection_.disconnected (proxy, ACE_TRY_ENV); } -template<class PROXY, class C, class I, class L> void -TAO_ESF_Copy_On_Read<PROXY,C,I,L>:: +template<class PROXY, class COLLECTION, class ITERATOR, class ACE_LOCK> void +TAO_ESF_Copy_On_Read<PROXY,COLLECTION,ITERATOR,ACE_LOCK>:: shutdown (CORBA::Environment &ACE_TRY_ENV) { - ACE_GUARD (L, ace_mon, this->lock_); + ACE_GUARD (ACE_LOCK, ace_mon, this->lock_); this->collection_.shutdown (ACE_TRY_ENV); } diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.h index 695bfbbcb1d..5286ea0adc2 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Read.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Copy_On_Read -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Copy_On_Read.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_COPY_ON_READ_H #define TAO_ESF_COPY_ON_READ_H @@ -30,25 +22,24 @@ template<class Target> class TAO_ESF_Worker; // **************************************************************** +/** + * @class TAO_ESF_Copy_On_Read + * + * @brief Implement the Copy_On_Read protocol + * + * + * The class is parametric on the kind of collection and locking + * mechanism used. + */ template<class PROXY, class COLLECTION, class ITERATOR, class ACE_LOCK> class TAO_ESF_Copy_On_Read : public TAO_ESF_Proxy_Collection<PROXY> { - // = TITLE - // TAO_ESF_Copy_On_Read - // - // = DESCRIPTION - // Implement the Copy_On_Read protocol - // The class is parametric on the kind of collection and locking - // mechanism used. - // - // = TODO - // public: + /// Constructors TAO_ESF_Copy_On_Read (void); TAO_ESF_Copy_On_Read (const COLLECTION &collection); - // Constructors - // = The TAO_ESF_Proxy methods + // = The TAO_ESF_Proxy_Collection methods virtual void for_each (TAO_ESF_Worker<PROXY> *worker, CORBA::Environment &ACE_TRY_ENV); virtual void connected (PROXY *proxy, diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.cpp b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.cpp index d3d33f744a8..d3425ef7485 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.cpp +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.cpp @@ -79,8 +79,8 @@ TAO_ESF_Copy_On_Write<PROXY,COLLECTION,ITERATOR,ACE_SYNCH_USE>:: } } -template<class PROXY, class C, class I, ACE_SYNCH_DECL> void -TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: +template<class PROXY, class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> void +TAO_ESF_Copy_On_Write<PROXY,COLLECTION,ITERATOR,ACE_SYNCH_USE>:: connected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) { @@ -94,8 +94,8 @@ TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: ace_mon.copy->collection.connected (proxy, ACE_TRY_ENV); } -template<class PROXY, class C, class I, ACE_SYNCH_DECL> void -TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: +template<class PROXY, class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> void +TAO_ESF_Copy_On_Write<PROXY,COLLECTION,ITERATOR,ACE_SYNCH_USE>:: reconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) { @@ -109,8 +109,8 @@ TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: ace_mon.copy->collection.reconnected (proxy, ACE_TRY_ENV); } -template<class PROXY, class C, class I, ACE_SYNCH_DECL> void -TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: +template<class PROXY, class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> void +TAO_ESF_Copy_On_Write<PROXY,COLLECTION,ITERATOR,ACE_SYNCH_USE>:: disconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) { @@ -123,8 +123,8 @@ TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: ace_mon.copy->collection.disconnected (proxy, ACE_TRY_ENV); } -template<class PROXY, class C, class I, ACE_SYNCH_DECL> void -TAO_ESF_Copy_On_Write<PROXY,C,I,ACE_SYNCH_USE>:: +template<class PROXY, class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> void +TAO_ESF_Copy_On_Write<PROXY,COLLECTION,ITERATOR,ACE_SYNCH_USE>:: shutdown (CORBA::Environment &ACE_TRY_ENV) { // We need to perform a copy to follow the protocol. diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.h index e7fd96273af..b45e26cbcf3 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Copy_On_Write.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Copy_On_Write -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/ESF/index.html -// -// ============================================================================ +/** + * @file ESF_Copy_On_Write.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_COPY_ON_WRITE_H #define TAO_ESF_COPY_ON_WRITE_H @@ -32,41 +24,40 @@ class TAO_ESF_Copy_On_Write_Collection public: TAO_ESF_Copy_On_Write_Collection (void); + /// Increment and decrement the reference count CORBA::ULong _incr_refcnt (void); CORBA::ULong _decr_refcnt (void); - // Increment and decrement the reference count + /// The actual collection COLLECTION collection; - // The actual collection private: + /// The reference count CORBA::ULong refcount_; - // The reference count }; // **************************************************************** +/** + * @class TAO_ESF_Copy_On_Write_Read_Guard + * + * @brief TAO_ESF_Copy_On_Guard + * + * This helper class atomically increments the reference count of + * a TAO_ESF_Copy_On_Write_Collection and reads the current + * collection in the Copy_On_Write class. + */ template<class COLLECTION, class ITERATOR, class ACE_LOCK> class TAO_ESF_Copy_On_Write_Read_Guard { - // = TITLE - // TAO_ESF_Copy_On_Guard - // - // = DESCRIPTION - // This helper class atomically increments the reference count of - // a TAO_ESF_Copy_On_Write_Collection and reads the current - // collection in the Copy_On_Write class. - // - // = TODO - // public: + /// Constructor typedef TAO_ESF_Copy_On_Write_Collection<COLLECTION,ITERATOR> Collection; TAO_ESF_Copy_On_Write_Read_Guard (ACE_LOCK &mutex, Collection *&collection); - // Constructor + /// Destructor ~TAO_ESF_Copy_On_Write_Read_Guard (void); - // Destructor Collection *collection; @@ -76,30 +67,29 @@ private: // **************************************************************** +/** + * @class TAO_ESF_Copy_On_Write_Write_Guard + * + * @brief TAO_ESF_Copy_On_Write_Guard + * + * This helper class atomically increments the reference count of + * a TAO_ESF_Copy_On_Write_Collection and reads the current + * collection in the Copy_On_Write class. + */ template<class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> class TAO_ESF_Copy_On_Write_Write_Guard { - // = TITLE - // TAO_ESF_Copy_On_Write_Guard - // - // = DESCRIPTION - // This helper class atomically increments the reference count of - // a TAO_ESF_Copy_On_Write_Collection and reads the current - // collection in the Copy_On_Write class. - // - // = TODO - // public: + /// Constructor typedef TAO_ESF_Copy_On_Write_Collection<COLLECTION,ITERATOR> Collection; TAO_ESF_Copy_On_Write_Write_Guard (ACE_SYNCH_MUTEX_T &mutex, ACE_SYNCH_CONDITION_T &cond, int &pending_writes, int &writing_flag, Collection*& collection); - // Constructor + /// Destructor ~TAO_ESF_Copy_On_Write_Write_Guard (void); - // Destructor Collection *copy; @@ -113,27 +103,26 @@ private: // **************************************************************** +/** + * @class TAO_ESF_Copy_On_Write + * + * @brief TAO_ESF_Copy_On_Write + * + * Implement the Copy_On_Write protocol + * The class is parametric on the kind of collection and locking + * mechanism used. + */ template<class PROXY, class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> class TAO_ESF_Copy_On_Write : public TAO_ESF_Proxy_Collection<PROXY> { - // = TITLE - // TAO_ESF_Copy_On_Write - // - // = DESCRIPTION - // Implement the Copy_On_Write protocol - // The class is parametric on the kind of collection and locking - // mechanism used. - // - // = TODO - // public: + /// Constructor typedef TAO_ESF_Copy_On_Write_Read_Guard<COLLECTION,ITERATOR,ACE_SYNCH_MUTEX_T> Read_Guard; typedef TAO_ESF_Copy_On_Write_Write_Guard<COLLECTION,ITERATOR,ACE_SYNCH_USE> Write_Guard; TAO_ESF_Copy_On_Write (void); - // Constructor + /// Destructor ~TAO_ESF_Copy_On_Write (void); - // Destructor // = The TAO_ESF_Proxy methods virtual void for_each (TAO_ESF_Worker<PROXY> *worker, @@ -149,22 +138,24 @@ public: private: typedef TAO_ESF_Copy_On_Write_Collection<COLLECTION,ITERATOR> Collection; + /// A mutex to serialize access to the collection pointer. ACE_SYNCH_MUTEX_T mutex_; - // A mutex to serialize access to the collection pointer. + /// Number of pending writes int pending_writes_; - // Number of pending writes + /** + * If non-zero then a thread is changing the collection. Many + * threads can use the collection simulatenously, but only one + * change it. + */ int writing_; - // If non-zero then a thread is changing the collection. Many - // threads can use the collection simulatenously, but only one - // change it. + /// A condition variable to wait to synchronize multiple writers. ACE_SYNCH_CONDITION_T cond_; - // A condition variable to wait to synchronize multiple writers. + /// The collection, with reference counting added Collection *collection_; - // The collection, with reference counting added }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Defaults.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Defaults.h index 77846dcee44..9d391cccf2b 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Defaults.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Defaults.h @@ -1,21 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Defaults -// -// = DESCRIPTION -// In this file we set the compile time defaults for the framework. -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// ============================================================================ +/** + * @file ESF_Defaults.h + * + * $Id$ + * + * In this file we set the compile time defaults for the framework. + * + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_DEFAULTS_H #define TAO_ESF_DEFAULTS_H diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Changes.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Changes.h index 6b9bf11ff0a..2293367c036 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Changes.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Changes.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_Collection -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Proxy_Collection.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_DELAYED_CHANGES_H #define TAO_ESF_DELAYED_CHANGES_H @@ -34,62 +26,60 @@ template<class Target,class Object> class TAO_ESF_Disconnected_Command; template<class Target,class Object> class TAO_ESF_Reconnected_Command; template<class Target> class TAO_ESF_Shutdown_Command; +/** + * @class TAO_ESF_Delayed_Changes + * + * @brief TAO_ESF_Delayed_Operations + * + * This class implements the Delayed Operations protocol to solve + * the concurrency challenges outlined in the documentation of + * TAO_ESF_Proxy_Collection. + * In short the class delays changes by putting them on an + * "operation queue", the operations are stored as command objects + * in this queue and executed once the system is quiescent + * (i.e. no threads are iterating over the collection). + * The algorithm implemented so far is: + * - If a thread is using the set then it increases the busy + * count, this is done by calling the busy() method. Once the + * thread has stopped using the collection the idle() method is + * invoked and the busy count is decreased. + * A helper class (Busy_Lock) is used to hide this protocol + * behind the familiar GUARD idiom. + * - If the busy count reaches the busy_hwm then the thread must + * wait until the count reaches 0 again. + * This can be used to control the maximum concurrency in the + * EC, matching it (for example) with the number of + * processors. Setting the concurrency to a high value (say one + * million) allows for an arbitrary number of threads to execute + * concurrently. + * - If a modification is posted to the collection we need to + * execute it at some point. + * Just using the busy_hwm would not work, the HWM may not be + * reached ever, so another form of control is needed. + * Instead we use another counter, that keeps track of how many + * threads have used the set since the modification was + * posted. If this number of threads reaches max_write_delay then + * we don't allow any more threads to go in, eventually the + * thread count reaches 0 and we can proceed with the operations. + * - There is one aspect of concurrency that can be problematic: if + * thread pushes events as part of an upcall then the same thread + * could be counted twice, we need to keep track of the threads + * that are dispatching events and not increase (or decrease) the + * reference count when a thread iterates twice over the same + * set. + * This solves the major problems, but there are other issues to + * be addressed: + * + How do we ensure that the operations are eventually executed? + * + How do we simplify the execution of the locking protocol for + * clients of this class? + * + How do we minimize overhead for single threaded execution? + * + How do we minimize the overhead for the cases where the + * threads dispatching events don't post changes to the + * collection? + */ template<class PROXY, class COLLECTION, class ITERATOR, ACE_SYNCH_DECL> class TAO_ESF_Delayed_Changes : public TAO_ESF_Proxy_Collection<PROXY> { - // = TITLE - // TAO_ESF_Delayed_Operations - // - // = DESCRIPTION - // This class implements the Delayed Operations protocol to solve - // the concurrency challenges outlined in the documentation of - // TAO_ESF_Proxy_Collection. - // In short the class delays changes by putting them on an - // "operation queue", the operations are stored as command objects - // in this queue and executed once the system is quiescent - // (i.e. no threads are iterating over the collection). - // - // The algorithm implemented so far is: - // - If a thread is using the set then it increases the busy - // count, this is done by calling the busy() method. Once the - // thread has stopped using the collection the idle() method is - // invoked and the busy count is decreased. - // A helper class (Busy_Lock) is used to hide this protocol - // behind the familiar GUARD idiom. - // - If the busy count reaches the busy_hwm then the thread must - // wait until the count reaches 0 again. - // This can be used to control the maximum concurrency in the - // EC, matching it (for example) with the number of - // processors. Setting the concurrency to a high value (say one - // million) allows for an arbitrary number of threads to execute - // concurrently. - // - If a modification is posted to the collection we need to - // execute it at some point. - // Just using the busy_hwm would not work, the HWM may not be - // reached ever, so another form of control is needed. - // Instead we use another counter, that keeps track of how many - // threads have used the set since the modification was - // posted. If this number of threads reaches max_write_delay then - // we don't allow any more threads to go in, eventually the - // thread count reaches 0 and we can proceed with the operations. - // - // - There is one aspect of concurrency that can be problematic: if - // thread pushes events as part of an upcall then the same thread - // could be counted twice, we need to keep track of the threads - // that are dispatching events and not increase (or decrease) the - // reference count when a thread iterates twice over the same - // set. - // - // This solves the major problems, but there are other issues to - // be addressed: - // + How do we ensure that the operations are eventually executed? - // + How do we simplify the execution of the locking protocol for - // clients of this class? - // + How do we minimize overhead for single threaded execution? - // + How do we minimize the overhead for the cases where the - // threads dispatching events don't post changes to the - // collection? - // public: TAO_ESF_Delayed_Changes (void); TAO_ESF_Delayed_Changes (const COLLECTION &collection); @@ -137,9 +127,9 @@ private: CORBA::ULong write_delay_count_; + /// Control variables for the concurrency policies. CORBA::ULong busy_hwm_; CORBA::ULong max_write_delay_; - // Control variables for the concurrency policies. ACE_Unbounded_Queue<ACE_Command_Base*> command_queue_; }; diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Command.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Command.h index b66259c2c4e..ee0ab0f3ada 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Command.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Delayed_Command.h @@ -1,18 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Delayed_Command -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// ============================================================================ +/** + * @file ESF_Delayed_Command.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_DELAYED_COMMAND_H #define TAO_ESF_DELAYED_COMMAND_H @@ -23,162 +18,151 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_Connected_Command + * + * @brief Implements a Command object that invokes the connected_i() + * method on the target, passing an argument of type Object. + * + * <H2>Memory Managment</H2> + * It does not assume ownership of Object nor the Target + * arguments. + * Usually allocated from the heap or an allocator; but it is not + * self-managed. + * + * <H2>Locking</H2> + * No provisions for locking, access must be serialized + * externally. + */ template<class Target, class Object> class TAO_ESF_Connected_Command : public ACE_Command_Base { - // = TITLE - // ESF_Connected_Command - // - // = DESCRIPTION - // Implements a Command object that invokes the connected_i() method - // on the target, passing an argument of type Object. - // - // = MEMORY MANAGMENT - // It does not assume ownership of Object nor the Target - // arguments. - // Usually allocated from the heap or an allocator; but it is not - // self-managed. - // - // = LOCKING - // No provisions for locking, access must be serialized - // externally. - // - // = TODO - // public: + /// constructor... TAO_ESF_Connected_Command (Target *target, Object *object); - // constructor... + /// The callback method, if the argument is not nil it is interpreted + /// as a CORBA::Environment. virtual int execute (void *arg); - // The callback method, if the argument is not nil it is interpreted - // as a CORBA::Environment. private: + /// The target Target *target_; - // The target + /// The argument Object *object_; - // The argument }; // **************************************************************** +/** + * @class TAO_ESF_Reconnected_Command + * + * @brief Implements a Command object that invokes the reconnected_i() + * method on the target, passing an argument of type Object. + * + * <H2>Memory Managment</H2> + * It does not assume ownership of Object nor the Target + * arguments. + * Usually allocated from the heap or an allocator; but it is not + * self-managed. + * + * <H2>Locking</H2> + * No provisions for locking, access must be serialized + * externally. + */ template<class Target, class Object> class TAO_ESF_Reconnected_Command : public ACE_Command_Base { - // = TITLE - // ESF_Reconnected_Command - // - // = DESCRIPTION - // Implements a Command object that invokes the reconnected_i() method - // on the target, passing an argument of type Object. - // - // = MEMORY MANAGMENT - // It does not assume ownership of Object nor the Target - // arguments. - // Usually allocated from the heap or an allocator; but it is not - // self-managed. - // - // = LOCKING - // No provisions for locking, access must be serialized - // externally. - // - // = TODO - // public: + /// constructor... TAO_ESF_Reconnected_Command (Target *target, Object *object); - // constructor... + /// The callback method, if the argument is not nil it is interpreted + /// as a CORBA::Environment. virtual int execute (void *arg); - // The callback method, if the argument is not nil it is interpreted - // as a CORBA::Environment. private: + /// The target Target *target_; - // The target + /// The argument Object *object_; - // The argument }; // **************************************************************** +/** + * @class TAO_ESF_Disconnected_Command + * + * @brief Implements a Command object that invokes the + * disconnected_i() method on the target, passing an argument of type + * Object. + * + * <H2>Memory Managment</H2> + * It does not assume ownership of Object nor the Target + * arguments. + * Usually allocated from the heap or an allocator; but it is not + * self-managed. + * + * <H2>Locking</H2> + * No provisions for locking, access must be serialized + * externally. + */ template<class Target, class Object> class TAO_ESF_Disconnected_Command : public ACE_Command_Base { - // = TITLE - // ESF_Disconnected_Command - // - // = DESCRIPTION - // Implements a Command object that invokes the disconnected_i() - // method on the target, passing an argument of type Object. - // - // = MEMORY MANAGMENT - // It does not assume ownership of Object nor the Target - // arguments. - // Usually allocated from the heap or an allocator; but it is not - // self-managed. - // - // = LOCKING - // No provisions for locking, access must be serialized - // externally. - // - // = TODO - // public: + /// constructor... TAO_ESF_Disconnected_Command (Target *target, Object *object); - // constructor... + /// The callback method, if the argument is not nil it is interpreted + /// as a CORBA::Environment. virtual int execute (void *arg); - // The callback method, if the argument is not nil it is interpreted - // as a CORBA::Environment. private: + /// The target Target *target_; - // The target + /// The argument Object *object_; - // The argument }; // **************************************************************** +/** + * @class TAO_ESF_Shutdown_Command + * + * @brief Implements a Command object that invokes the shutdown_i() + * method on the target, passing an argument of type Object. + * + * <H2>Memory Management</H2> + * It does not assume ownership of Object nor the Target + * arguments. + * Usually allocated from the heap or an allocator; but it is not + * self-managed. + * + * <H2>Locking</H2> + * No provisions for locking, access must be serialized + * externally. + */ template<class Target> class TAO_ESF_Shutdown_Command : public ACE_Command_Base { - // = TITLE - // ESF_Shutdown_Command - // - // = DESCRIPTION - // Implements a Command object that invokes the shutdown_i() - // method on the target, passing an argument of type Object. - // - // = MEMORY MANAGMENT - // It does not assume ownership of Object nor the Target - // arguments. - // Usually allocated from the heap or an allocator; but it is not - // self-managed. - // - // = LOCKING - // No provisions for locking, access must be serialized - // externally. - // - // = TODO - // public: + /// constructor... TAO_ESF_Shutdown_Command (Target *target); - // constructor... + /// The callback method, if the argument is not nil it is interpreted + /// as a CORBA::Environment. virtual int execute (void *arg); - // The callback method, if the argument is not nil it is interpreted - // as a CORBA::Environment. private: + /// The target Target *target_; - // The target }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Immediate_Changes.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Immediate_Changes.h index 89d35b9f71d..333ca8fa0ae 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Immediate_Changes.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Immediate_Changes.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_Collection -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Proxy_Collection.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_IMMEDIATE_CHANGES_H #define TAO_ESF_IMMEDIATE_CHANGES_H @@ -26,14 +18,15 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_Immediate_Changes + * + * @brief Implement the Immediate_Changes strategy + * + */ template<class PROXY, class COLLECTION, class ITERATOR, class ACE_LOCK> class TAO_ESF_Immediate_Changes : public TAO_ESF_Proxy_Collection<PROXY> { - // = TITLE - // TAO_ESF_Immediate_Changes - // - // = DESCRIPTION - // Implement the Immediate_ public: TAO_ESF_Immediate_Changes (void); TAO_ESF_Immediate_Changes (const COLLECTION &collection); diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.cpp b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.cpp index a824932498e..8cef341eb62 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.cpp +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.cpp @@ -13,47 +13,48 @@ ACE_RCSID(ESF, ESF_Peer_Admin, "$Id$") -#if defined (__BORLANDC__) - -template<class EC,class P,class I,class R> -TAO_ESF_Peer_Admin<EC,P,I,R>::TAO_ESF_Peer_Admin (EC *ec) - : TAO_ESF_Proxy_Admin<EC,P,I> (ec) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE, class PEER> +TAO_ESF_Peer_Admin<EVENT_CHANNEL,PROXY,INTERFACE,PEER>:: + TAO_ESF_Peer_Admin (EVENT_CHANNEL *ec) + : TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE> (ec) { } -#endif /* __BORLANDC__ */ - -template<class EC, class P,class I, class PEER> -TAO_ESF_Peer_Admin<EC,P,I,PEER>::~TAO_ESF_Peer_Admin (void) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE, class PEER> +TAO_ESF_Peer_Admin<EVENT_CHANNEL,PROXY,INTERFACE,PEER>:: + ~TAO_ESF_Peer_Admin (void) { } -template<class EC, class P,class I, class PEER> void -TAO_ESF_Peer_Admin<EC,P,I,PEER>::peer_connected (PEER *peer, - CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE, class PEER> void +TAO_ESF_Peer_Admin<EVENT_CHANNEL,PROXY,INTERFACE,PEER>:: + peer_connected (PEER *peer, + CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { - TAO_ESF_Peer_Connected<P,PEER> worker (peer); + TAO_ESF_Peer_Connected<PROXY,PEER> worker (peer); this->for_each (&worker, ACE_TRY_ENV); } -template<class EC, class P,class I, class PEER> void -TAO_ESF_Peer_Admin<EC,P,I,PEER>::peer_reconnected (PEER *peer, - CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE, class PEER> void +TAO_ESF_Peer_Admin<EVENT_CHANNEL,PROXY,INTERFACE,PEER>:: + peer_reconnected (PEER *peer, + CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { - TAO_ESF_Peer_Reconnected<P,PEER> worker (peer); + TAO_ESF_Peer_Reconnected<PROXY,PEER> worker (peer); this->for_each (&worker, ACE_TRY_ENV); } -template<class EC, class P,class I, class PEER> void -TAO_ESF_Peer_Admin<EC,P,I,PEER>::peer_disconnected (PEER *peer, - CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE, class PEER> void +TAO_ESF_Peer_Admin<EVENT_CHANNEL,PROXY,INTERFACE,PEER>:: + peer_disconnected (PEER *peer, + CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { - TAO_ESF_Peer_Disconnected<P,PEER> worker (peer); + TAO_ESF_Peer_Disconnected<PROXY,PEER> worker (peer); this->for_each (&worker, ACE_TRY_ENV); } diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.h index ec64d803121..6c48183e553 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Peer_Admin -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Peer_Admin.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_PEER_ADMIN_H #define TAO_ESF_PEER_ADMIN_H @@ -26,63 +18,76 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_Peer_Admin + * + * @brief Extend the Proxy_Admin interface to provide methods for + * filtering + * + * Some Event Services that perform filtering have to propagate + * the consumer connect/disconnect activities to the suppliers, + * and vice-versa. + * In that scenario the ESF_Proxy_Admin<> interface is augmented + * with connected()/reconnected()/disconnected() operations for + * the proxy peers (i.e. the ProxySuppliers for the ProxyConsumers + * and vice-versa). + * + * <H2>Requirements</H2> + * + * In addition to the requirements imposed by ESF_Proxy_Admin<> + * the PROXY interface must implement: + * + * @verbatim + * void connected (PEER *peer, CORBA::Environment&) throw (); + * void reconnected (PEER *peer, CORBA::Environment&) throw (); + * void disconnected (PEER *peer, CORBA::Environment&) throw (); + * @endverbatim + * + * Similarly, the PEER interface must implement: + * + * @verbatim + * void connected (PROXY *proxy, CORBA::Environment&) throw (); + * void reconnected (PROXY *proxy, CORBA::Environment&) throw (); + * void disconnected (PROXY *proxy, CORBA::Environment&) throw (); + * @endverbatim + */ template<class EVENT_CHANNEL, class PROXY, class INTERFACE, class PEER> class TAO_ESF_Peer_Admin : public TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE> { - // = TITLE - // ESF_Peer_Admin - // - // = DESCRIPTION - // Some Event Services that perform filtering have to propagate - // the consumer connect/disconnect activities to the suppliers, - // and vice-versa. - // In that scenario the ESF_Proxy_Admin<> interface is augmented - // with connected()/reconnected()/disconnected() operations for - // the proxy peers (i.e. the ProxySuppliers for the ProxyConsumers - // and vice-versa). - // - // = REQUIREMENTS - // In addition to the requirements imposed by ESF_Proxy_Admin<> - // the PROXY interface must implement: - // - // void connected (PEER *peer, CORBA::Environment&) throw (); - // void reconnected (PEER *peer, CORBA::Environment&) throw (); - // void disconnected (PEER *peer, CORBA::Environment&) throw (); - // - // Similarly, the PEER interface must implement: - // - // void connected (PROXY *proxy, CORBA::Environment&) throw (); - // void reconnected (PROXY *proxy, CORBA::Environment&) throw (); - // void disconnected (PROXY *proxy, CORBA::Environment&) throw (); - // public: + /// Constructor TAO_ESF_Peer_Admin (EVENT_CHANNEL *ec); - // Constructor + /// destructor virtual ~TAO_ESF_Peer_Admin (void); - // destructor + /** + * A <peer> has connected, this is invoked when the peer's client + * has invoked the connect_xxx_yyy() method. + * The default implementation is a no-op. + */ virtual void peer_connected (PEER *peer, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // A <peer> has connected, this is invoked when the peer's client - // has invoked the connect_xxx_yyy() method. - // The default implementation is a no-op. + /** + * A <peer> has reconnected, i.e. its client has invoked the + * connect_xxx_yyy() method, but the peer was connected already. + * The default implementation delegates on the collection + * <reconnected> method + */ virtual void peer_reconnected (PEER *peer, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // A <peer> has reconnected, i.e. its client has invoked the - // connect_xxx_yyy() method, but the peer was connected already. - // The default implementation delegates on the collection - // <reconnected> method + /** + * A <peer> has been disconnected. The default implementation + * removes the object from the collection and deactivates the + * proxy. + */ virtual void peer_disconnected (PEER *peer, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // A <peer> has been disconnected. The default implementation - // removes the object from the collection and deactivates the - // proxy. }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.i b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.i index 5a6baac1c42..cfa1da318d3 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.i +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Admin.i @@ -1,11 +1 @@ // $Id$ - -#if !defined (__BORLANDC__) - -template<class EC,class P,class I,class R> ACE_INLINE -TAO_ESF_Peer_Admin<EC,P,I,R>::TAO_ESF_Peer_Admin (EC *ec) - : TAO_ESF_Proxy_Admin<EC,P,I> (ec) -{ -} - -#endif /* __BORLANDC__ */ diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Workers.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Workers.h index b1939cefd81..7819ee564ff 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Workers.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Peer_Workers.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Peer_Connected -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Peer_Connected.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/ESF/index.html + */ #ifndef TAO_ESF_PEER_WORKERS_H #define TAO_ESF_PEER_WORKERS_H @@ -26,16 +18,17 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_Peer_Connected + * + * Helper class. + * Used to iterate over a Proxy_Collection and invoke: + * PROXY->connected (peer); + * peer->connected (proxy); + */ template<class PROXY, class PEER> class TAO_ESF_Peer_Connected : public TAO_ESF_Worker<PROXY> { - // = DESCRIPTION - // Helper class. - // Used to iterate over a Proxy_Collection and invoke: - // - // PROXY->connected (peer); - // peer->connected (proxy); - // public: TAO_ESF_Peer_Connected (PEER *peer); @@ -48,16 +41,17 @@ private: // **************************************************************** +/** + * @class TAO_ESF_Peer_Reconnected + * + * Helper class. + * Used to iterate over a Proxy_Collection and invoke: + * PROXY->reconnected (peer); + * peer->reconnected (proxy); + */ template<class PROXY, class PEER> class TAO_ESF_Peer_Reconnected : public TAO_ESF_Worker<PROXY> { - // = DESCRIPTION - // Helper class. - // Used to iterate over a Proxy_Collection and invoke: - // - // PROXY->reconnected (peer); - // peer->reconnected (proxy); - // public: TAO_ESF_Peer_Reconnected (PEER *peer); @@ -70,16 +64,17 @@ private: // **************************************************************** +/** + * @class TAO_ESF_Peer_Disconnected + * + * Helper class. + * Used to iterate over a Proxy_Collection and invoke: + * PROXY->disconnected (peer); + * peer->disconnected (proxy); + */ template<class PROXY, class PEER> class TAO_ESF_Peer_Disconnected : public TAO_ESF_Worker<PROXY> { - // = DESCRIPTION - // Helper class. - // Used to iterate over a Proxy_Collection and invoke: - // - // PROXY->disconnected (peer); - // peer->disconnected (proxy); - // public: TAO_ESF_Peer_Disconnected (PEER *peer); diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.cpp b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.cpp index d44befa55c0..d1ad36326cf 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.cpp +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.cpp @@ -13,43 +13,47 @@ ACE_RCSID(ESF, ESF_Proxy_Admin, "$Id$") -template<class EC, class P,class I> -TAO_ESF_Proxy_Admin<EC,P,I>::TAO_ESF_Proxy_Admin (EC *ec) - : event_channel_ (ec) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + TAO_ESF_Proxy_Admin (EVENT_CHANNEL *ec) + : event_channel_ (ec) { this->event_channel_->create_proxy_collection (this->collection_); } -template<class EC, class P,class I> -TAO_ESF_Proxy_Admin<EC,P,I>::~TAO_ESF_Proxy_Admin (void) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + ~TAO_ESF_Proxy_Admin (void) { this->event_channel_->destroy_proxy_collection (this->collection_); } -template<class EC, class P,class I> I* -TAO_ESF_Proxy_Admin<EC,P,I>::obtain (CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> INTERFACE* +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + obtain (CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { - P* proxy; + PROXY* proxy; this->event_channel_->create_proxy (proxy); PortableServer::ServantBase_var holder = proxy; - ACE_TYPENAME P::_var_type result = + ACE_TYPENAME PROXY::_var_type result = proxy->activate (ACE_TRY_ENV); - ACE_CHECK_RETURN (I::_nil ()); + ACE_CHECK_RETURN (INTERFACE::_nil ()); this->collection_->connected (proxy, ACE_TRY_ENV); - ACE_CHECK_RETURN (I::_nil ()); + ACE_CHECK_RETURN (INTERFACE::_nil ()); return result._retn (); } -template<class EC, class P,class I> void -TAO_ESF_Proxy_Admin<EC,P,I>::shutdown (CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> void +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + shutdown (CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { - TAO_ESF_Shutdown_Proxy<P> worker; + TAO_ESF_Shutdown_Proxy<PROXY> worker; this->collection_->for_each (&worker, ACE_TRY_ENV); ACE_CHECK; // Cannot happen, just following the discipline. @@ -57,24 +61,27 @@ TAO_ESF_Proxy_Admin<EC,P,I>::shutdown (CORBA::Environment &ACE_TRY_ENV) this->collection_->shutdown (ACE_TRY_ENV); } -template<class EC, class P,class I> void -TAO_ESF_Proxy_Admin<EC,P,I>::connected (P *, - CORBA::Environment &) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> void +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + connected (PROXY *, + CORBA::Environment &) ACE_THROW_SPEC (()) { } -template<class EC, class P,class I> void -TAO_ESF_Proxy_Admin<EC,P,I>::reconnected (P *proxy, - CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> void +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + reconnected (PROXY *proxy, + CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { this->collection_->reconnected (proxy, ACE_TRY_ENV); } -template<class EC, class P,class I> void -TAO_ESF_Proxy_Admin<EC,P,I>::disconnected (P *proxy, - CORBA::Environment &ACE_TRY_ENV) +template<class EVENT_CHANNEL, class PROXY, class INTERFACE> void +TAO_ESF_Proxy_Admin<EVENT_CHANNEL,PROXY,INTERFACE>:: + disconnected (PROXY *proxy, + CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()) { proxy->deactivate (ACE_TRY_ENV); diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.h index 613281fc85a..137ad662f75 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Admin.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_Admin -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Proxy_Admin.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_PROXY_ADMIN_H #define TAO_ESF_PROXY_ADMIN_H @@ -27,100 +19,116 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_Proxy_Admin + * + * @brief Implement common tasks in the Admin interfaces. + * + * <H2>Requirements</H2> + * + * The EVENT_CHANNEL interface must implement: + * + * @verbatim + * void create_proxy (PROXY*&); + * // create a new proxy + * + * void destroy_proxy (PROXY*); + * // destroy a proxy + * + * void create_proxy_collection (TAO_ESF_Proxy_Collection<PROXY>*&); + * // create a proxy collection + * + * void destroy_proxy_collection (TAO_ESF_Proxy_Collection<PROXY>*&); + * // destroy a proxy collection + * @endverbatim + * + * In addition to the requirements imposed by + * TAO_ESF_Proxy_Collection<>, the PROXY interface must define: + * + * @verbatim + * typename .... _ptr_type; + * // The T_ptr for the IDL interface implemented by the PROXY. + * + * typename .... _var_type; + * // The T_var for the IDL interface implemented by the PROXY. + * + * PROXY::_ptr_type + * PROXY::activate (CORBA::Environment &) throw (); + * // activate the proxy and return the object reference + * @endverbatim + * + */ template<class EVENT_CHANNEL, class PROXY, class INTERFACE> class TAO_ESF_Proxy_Admin { - // = TITLE - // ESF_Proxy_Admin - // - // = DESCRIPTION - // Implement common tasks in the Admin interfaces. - // - // = REQUIREMENTS - // - // The EVENT_CHANNEL interface must implement: - // - // void create_proxy (PROXY*&); - // // create a new proxy - // void destroy_proxy (PROXY*); - // // destroy a proxy - // - // void create_proxy_collection (TAO_ESF_Proxy_Collection<PROXY>*&); - // // create a proxy collection - // void destroy_proxy_collection (TAO_ESF_Proxy_Collection<PROXY>*&); - // // destroy a proxy collection - // - // In addition to the requirements imposed by - // TAO_ESF_Proxy_Collection<>, the PROXY interface must define: - // - // typename .... _ptr_type; - // // The T_ptr for the IDL interface implemented by the PROXY. - // typename .... _var_type; - // // The T_var for the IDL interface implemented by the PROXY. - // - // PROXY::_ptr_type - // PROXY::activate (CORBA::Environment &) throw (); - // // activate the proxy and return the object reference - // public: + /// Constructor, allocate the internal collection TAO_ESF_Proxy_Admin (EVENT_CHANNEL *ec); - // Constructor + /// Cleanup internal resources, destroy the internal collection virtual ~TAO_ESF_Proxy_Admin (void); - // destructor + /// Iterate over its internal collection. void for_each (TAO_ESF_Worker<PROXY> *worker, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // Iterate over its internal collection. - // @@ We should use INTERFACE::_ptr_type or PROXY::_ptr_type, but + // @TODO We should use INTERFACE::_ptr_type or PROXY::_ptr_type, but // the MSVC compiler (v6.0) gets confused when we do so. So we have // to choose for the lesser evil. The code works because TAO uses // pointers to implement the _ptr types, and that is OK because this // code is supposed to run under TAO only. + /// Create a new PROXY and activate it. virtual INTERFACE* obtain (CORBA::Environment &) ACE_THROW_SPEC (()); - // Create a new PROXY and activate it. + /** + * The Event Channel that owns this Admin object is going + * down. Invoke <shutdown> on all the proxies, cleanup the + * collection and prepare to terminate. + */ virtual void shutdown (CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // The Event Channel that owns this Admin object is going - // down. Invoke <shutdown> on all the proxies, cleanup the - // collection and prepare to terminate. + /** + * A <proxy> has connected, this is invoked when the proxy's client + * has invoked the connect_xxx_yyy() method. + * The default implementation is a no-op. + */ virtual void connected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // A <proxy> has connected, this is invoked when the proxy's client - // has invoked the connect_xxx_yyy() method. - // The default implementation is a no-op. + /** + * A <proxy> has reconnected, i.e. its client has invoked the + * connect_xxx_yyy() method, but the proxy was connected already. + * The default implementation delegates on the collection + * <reconnected> method + */ virtual void reconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // A <proxy> has reconnected, i.e. its client has invoked the - // connect_xxx_yyy() method, but the proxy was connected already. - // The default implementation delegates on the collection - // <reconnected> method + /** + * A <proxy> has been disconnected. The default implementation + * removes the object from the collection and deactivates the + * proxy. + */ virtual void disconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // A <proxy> has been disconnected. The default implementation - // removes the object from the collection and deactivates the - // proxy. protected: + /// The Event Channel we belong to EVENT_CHANNEL *event_channel_; - // The Event Channel we belong to private: + /// Shorthand for the Proxy collection typedef TAO_ESF_Proxy_Collection<PROXY> Collection; + /// The proxy collection object Collection *collection_; - // The supplier container. }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Collection.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Collection.h index 9f69b025d41..a7e61a655bf 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Collection.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_Collection.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_Collection -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Proxy_Collection.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_PROXY_COLLECTION_H #define TAO_ESF_PROXY_COLLECTION_H @@ -28,143 +20,138 @@ template<class Target> class TAO_ESF_Worker; +/** + * @class TAO_ESF_Proxy_Collection + * + * @brief ESF_Proxy_Collection + * + * Many components in an Event Service need to keep a collection + * of proxies; these collections must be able to cope with several + * concurrency issues: + * + Some threads may need to iterate over the collection and + * invoke a method on each element. Locking the collection + * while this is done is not feasible in all cases: under some + * configurations the same thread that is iterating over the + * collection may need to make changes to the set. + * + A recursive lock does not solve the concurrency problems + * because recursive changes to the collection still invalidate + * the iterators. + * + * There are several solutions to this problem (see the VARIANTS) + * section, and there is no single one that works bests in all + * cases. As usual, we wish the strategize the protocol used to + * serialize iterations and changes to the collection. This class + * encapsulates that protocol. + * + * The usual form of the Iterator pattern does not work well in + * this case: in several variants the synchronization protocol and + * the iteration loop must collaborate to work efficiently. + * Exposing an external iterator would require that every other + * component in the system can support all the synchronization + * protocols. It is possible to hide some of that complexity + * using heavy weight iterators, but their use is ackward, + * specially since the Koening-style iterators have become more + * popular. + * + * Regular member functions are used to insert, remove and update + * members of the collection and to shutdown (i.e. perform final + * cleanup operations). + * + * The class must also collaborate with other components of the + * EC to efficiently and safely perform memory managment of the + * members in the collection. + * + * The PROXY object must be reference counted with the following + * operations: + * + * + _incr_refcnt() - increment the reference count. + * + _decr_refcnt() - decrement the reference count. + * + * = VARIANTS + * + * We identify several sources of variation: + * + * + Immediate_Changes: in this variant the iteration in performed + * while holding some kind of synchronization primitive, such as a + * thread mutex, a recursive mutex, a RW lock, etc. + * This is only useful in configurations where a separate thread + * dispatches the events, and thus, can only be used with real + * locks. + * + Copy_On_Read: before performing the iteration the collection + * is duplicated into a temporary array. Thus no locks are held + * during the iteration. This is a very expensive approach, but + * useful in many cases. + * The kind of lock is also strategized in this case. + * + Copy_On_Write: this is very similar to the previous approach, + * but the collection is only duplicated when a change is required + * while some thread is performing an iteration. The iteration + * continues over the original copy, while the changes are + * performed in the duplicate. The new copy of the collection is + * used for any subsequent operations, the original is discarded + * when the last thread using it completes its work. + * This approach optimizes for the case where no changes are + * is duplicated into a temporary array. Thus no locks are held + * during the iteration. This is a very expensive approach, but + * useful in many cases. + * The kind of lock is also strategized in this case. + * + Delayed_Changes: before starting the iteration a counter is + * incremented, this counter is used to keep track of the number + * of threads concurrently using the collection. + * If a thread wants to perform a change to the collection it must + * first verify that there are no threads iterating over it. If + * there are any threads then the thread queues the modification + * for later execution, using the Command pattern. + * The kind of lock is strategized, as this approach is used in + * single threaded configurations. + * There are two main variations: + * - An upcall can result in new dispatches: in this case we + * have to keep track of a the list of current threads using + * a Set, to avoid dead-locks. The design is not complete, + * probably similar to the next one. + * - Otherwise we just need to control the concurrency using the + * algorithm described below. + * + * It assumes ownership of the proxies added to the collection, + * it increases the reference count. + * + * Locking is provided by derived classes. + */ template<class PROXY> class TAO_ESF_Proxy_Collection { - // = TITLE - // ESF_Proxy_Collection - // - // = DESCRIPTION - // Many components in an Event Service need to keep a collection - // of proxies; these collections must be able to cope with several - // concurrency issues: - // + Some threads may need to iterate over the collection and - // invoke a method on each element. Locking the collection - // while this is done is not feasible in all cases: under some - // configurations the same thread that is iterating over the - // collection may need to make changes to the set. - // + A recursive lock does not solve the concurrency problems - // because recursive changes to the collection still invalidate - // the iterators. - // - // There are several solutions to this problem (see the VARIANTS) - // section, and there is no single one that works bests in all - // cases. As usual, we wish the strategize the protocol used to - // serialize iterations and changes to the collection. This class - // encapsulates that protocol. - // - // The usual form of the Iterator pattern does not work well in - // this case: in several variants the synchronization protocol and - // the iteration loop must collaborate to work efficiently. - // Exposing an external iterator would require that every other - // component in the system can support all the synchronization - // protocols. It is possible to hide some of that complexity - // using heavy weight iterators, but their use is ackward, - // specially since the Koening-style iterators have become more - // popular. - // - // Regular member functions are used to insert, remove and update - // members of the collection and to shutdown (i.e. perform final - // cleanup operations). - // - // The class must also collaborate with other components of the - // EC to efficiently and safely perform memory managment of the - // members in the collection. - // - // = REQUIREMENTS - // The PROXY object must be reference counted with the following - // operations: - // - // _incr_refcnt() - increment the reference count. - // _decr_refcnt() - decrement the reference count. - // - // = VARIANTS - // - // We identify several sources of variation: - // - // + Immediate_Changes: in this variant the iteration in performed - // while holding some kind of synchronization primitive, such as a - // thread mutex, a recursive mutex, a RW lock, etc. - // This is only useful in configurations where a separate thread - // dispatches the events, and thus, can only be used with real - // locks. - // - // + Copy_On_Read: before performing the iteration the collection - // is duplicated into a temporary array. Thus no locks are held - // during the iteration. This is a very expensive approach, but - // useful in many cases. - // The kind of lock is also strategized in this case. - // - // + Copy_On_Write: this is very similar to the previous approach, - // but the collection is only duplicated when a change is required - // while some thread is performing an iteration. The iteration - // continues over the original copy, while the changes are - // performed in the duplicate. The new copy of the collection is - // used for any subsequent operations, the original is discarded - // when the last thread using it completes its work. - // This approach optimizes for the case where no changes are - // is duplicated into a temporary array. Thus no locks are held - // during the iteration. This is a very expensive approach, but - // useful in many cases. - // The kind of lock is also strategized in this case. - // - // + Delayed_Changes: before starting the iteration a counter is - // incremented, this counter is used to keep track of the number - // of threads concurrently using the collection. - // If a thread wants to perform a change to the collection it must - // first verify that there are no threads iterating over it. If - // there are any threads then the thread queues the modification - // for later execution, using the Command pattern. - // The kind of lock is strategized, as this approach is used in - // single threaded configurations. - // There are two main variations: - // - An upcall can result in new dispatches: in this case we - // have to keep track of a the list of current threads using - // a Set, to avoid dead-locks. - // IMPLEMENTATION: the design is not complete, probably - // similar to the next one. - // - Otherwise we just need to control the concurrency using the - // algorithm described below. - // - // - // = MEMORY MANAGMENT - // It assumes ownership of the proxies added to the collection, - // it increases the reference count. - // - // = LOCKING - // Locking is provided by derived classes. - // - // = TODO - // public: + /// destructor virtual ~TAO_ESF_Proxy_Collection (void); - // destructor + /** + * Iterate over the collection and invoke worker->work() for each + * member of the collection. + * This encapsulates + */ virtual void for_each (TAO_ESF_Worker<PROXY> *worker, CORBA::Environment &ACE_TRY_ENV) = 0; - // Iterate over the collection and invoke worker->work() for each - // member of the collection. - // This encapsulates + /// Insert a new element into the collection. The collection assumes + /// ownership of the element. virtual void connected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) = 0; - // Insert a new element into the collection. The collection assumes - // ownership of the element. + /** + * Insert an element into the collection. No errors can be raised + * if the element is already present. + * The collection assumes ownership, i.e. must invoke + * <proxy->_decr_refcnt()> if the element is already present in the + * collection. + */ virtual void reconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) = 0; - // Insert an element into the collection. No errors can be raised - // if the element is already present. - // The collection assumes ownership, i.e. must invoke - // <proxy->_decr_refcnt()> if the element is already present in the - // collection. + /// Remove an element from the collection. virtual void disconnected (PROXY *proxy, CORBA::Environment &ACE_TRY_ENV) = 0; - // Remove an element from the collection. + /// The EC is shutting down, must release all the elements. virtual void shutdown (CORBA::Environment &ACE_TRY_ENV) = 0; - // The EC is shutting down, must release all the elements. }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_List.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_List.h index 0c8b593d8a9..f32185095cc 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_List.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_List.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_List -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Proxy_List.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_PROXY_LIST_H #define TAO_ESF_PROXY_LIST_H @@ -28,32 +20,52 @@ #include "ace/Containers.h" +/// A concrete proxy collection. +/** + * Based on the ACE_Unbounded_Set<> collection, used a double + * linked list internally. + */ template<class PROXY> class TAO_ESF_Proxy_List { - // = DESCRIPTION - // A concrete proxy collection. - // Based on the ACE_Unbounded_Set<> collection, used a double - // linked list internally. - // public: + /// A typedef for the underlying implementaiton class typedef ACE_Unbounded_Set<PROXY*> Implementation; + + /// A typedef for the underlying iterator typedef ACE_Unbounded_Set_Iterator<PROXY*> Iterator; + /// Constructor TAO_ESF_Proxy_List (void); + /// Return the first element in the collection, or end() if there + /// are none ACE_Unbounded_Set_Iterator<PROXY*> begin (void); + + /// Return one past the last element in the collection ACE_Unbounded_Set_Iterator<PROXY*> end (void); + + /// Return the number of elements in the collection size_t size (void) const; + + /// Insert a new element to the collection void connected (PROXY *, - CORBA::Environment &); + CORBA::Environment &); + + /// Insert a new element that could be there already. void reconnected (PROXY *, CORBA::Environment &); + + /// Remove an element from the collection void disconnected (PROXY *, CORBA::Environment &); + + /// Shutdown the collection, i.e. remove all elements and release + /// resources void shutdown (CORBA::Environment &); private: + /// The underlying implementation object ACE_Unbounded_Set<PROXY*> impl_; }; diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RB_Tree.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RB_Tree.h index b4708000082..7e24374b339 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RB_Tree.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RB_Tree.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_RB_Tree -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Proxy_RB_Tree.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_PROXY_RB_TREE_H #define TAO_ESF_PROXY_RB_TREE_H @@ -28,6 +20,7 @@ #include "ace/RB_Tree.h" +/// Iterator class for a ACE_ESF_RB_Tree template<class PROXY> class TAO_ESF_Proxy_RB_Tree_Iterator { @@ -48,27 +41,54 @@ private: // **************************************************************** +/// Concrete Proxy collection based on ACE_RB_Tree +/** + * The Event Service Framework provides several alternatives for the + * underlying proxy collections. + * This version is based on Red-Black trees that offer good insertion, + * removal and lookup performance, but the iteration is slightly + * degraded. + */ template<class PROXY> class TAO_ESF_Proxy_RB_Tree { public: + /// A typedef for the underlying implementaiton class typedef ACE_RB_Tree<PROXY*,int,ACE_Less_Than<PROXY*>,ACE_Null_Mutex> Implementation; + + /// A typedef for the underlying iterator typedef TAO_ESF_Proxy_RB_Tree_Iterator<PROXY> Iterator; + /// Constructor TAO_ESF_Proxy_RB_Tree (void); + /// Return the first element in the collection, or end() if there + /// are none TAO_ESF_Proxy_RB_Tree_Iterator<PROXY> begin (void); + + /// Return one past the last element in the collection TAO_ESF_Proxy_RB_Tree_Iterator<PROXY> end (void); + + /// Return the number of elements in the collection size_t size (void) const; + + /// Insert a new element to the collection void connected (PROXY *, - CORBA::Environment &); + CORBA::Environment &); + + /// Insert a new element that could be there already. void reconnected (PROXY *, CORBA::Environment &); + /// Remove an element from the collection void disconnected (PROXY *, CORBA::Environment &); + + /// Shutdown the collection, i.e. remove all elements and release + /// resources void shutdown (CORBA::Environment &); private: + /// The underlying implementation object Implementation impl_; }; diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RefCount_Guard.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RefCount_Guard.h index 4ecc951fc8c..d42de3509aa 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RefCount_Guard.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Proxy_RefCount_Guard.h @@ -1,18 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Proxy_RefCount_Guard -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// ============================================================================ +/** + * @file ESF_Proxy_RefCount_Guard.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_PROXY_REFCOUNT_GUARD_H #define TAO_ESF_PROXY_REFCOUNT_GUARD_H @@ -23,45 +18,45 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_Proxy_RefCount_Guard + * + * @brief Reference count based guard. + * + * A common idiom used on event services is to increment a + * reference count before starting a long running operation. + * The system can then execute the operation without any risk of + * having the underlying object destroyed. The advantage of using + * a reference count is that no mutex or lock needs to be held + * while the operation is beign executed. + * This class implements that common idiom, but it also adds hooks + * to handle scenarios where more than one operation is performed + * while holding the reference count. + * + * @TODO: The type of lock could be parametric + */ template<class EVENT_CHANNEL, class PROXY> class TAO_ESF_Proxy_RefCount_Guard { - // = TITLE - // Reference count based guard. - // - // = DESCRIPTION - // A common idiom used on event services is to increment a - // reference count before starting a long running operation. - // The system can then execute the operation without any risk of - // having the underlying object destroyed. The advantage of using - // a reference count is that no mutex or lock needs to be held - // while the operation is beign executed. - // This class implements that common idiom, but it also adds hooks - // to handle scenarios where more than one operation is performed - // while holding the reference count. - // - // = TODO - // @@ The type of lock could be parametric - // public: + /// Constructor TAO_ESF_Proxy_RefCount_Guard (CORBA::ULong &refcount, EVENT_CHANNEL *ec, PROXY *proxy); - // Constructor + /// Destructor ~TAO_ESF_Proxy_RefCount_Guard (void); - // Destructor protected: + /// The reference count, if it gets to zero then the object must be + /// destroyed CORBA::ULong &refcount_; - // The reference count, if it gets to zero then the object must be - // destroyed + /// The event channel used to destroy the proxy EVENT_CHANNEL *event_channel_; - // The event channel used to destroy the proxy + /// The proxy whose lifetime is controlled by the reference count PROXY *proxy_; - // The proxy whose lifetime is controlled by the reference count }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_RefCount_Guard.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_RefCount_Guard.h index 05731bb9fa7..c8bbdc32731 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_RefCount_Guard.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_RefCount_Guard.h @@ -1,18 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_RefCount_Guard -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// ============================================================================ +/** + * @file ESF_RefCount_Guard.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_REFCOUNT_GUARD_H #define TAO_ESF_REFCOUNT_GUARD_H @@ -23,30 +18,31 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_ESF_RefCount_Guard + * + * @brief Reference count based guard. + * + * A common idiom used on event services is to increment a + * reference count before starting a long running operation. + * The system can then execute the operation without any risk of + * having the underlying object destroyed. The advantage of using + * a reference count is that no mutex or lock needs to be held + * while the operation is beign executed. + */ template<class T> class TAO_ESF_RefCount_Guard { - // = TITLE - // Reference count based guard. - // - // = DESCRIPTION - // A common idiom used on event services is to increment a - // reference count before starting a long running operation. - // The system can then execute the operation without any risk of - // having the underlying object destroyed. The advantage of using - // a reference count is that no mutex or lock needs to be held - // while the operation is beign executed. - // public: + /// Constructor TAO_ESF_RefCount_Guard (T &refcount); - // Constructor + /// Destructor ~TAO_ESF_RefCount_Guard (void); - // Destructor protected: + /// The reference count T &refcount_; - // The reference count }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Shutdown_Proxy.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Shutdown_Proxy.h index 8d3986f5133..e43728c04f0 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Shutdown_Proxy.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Shutdown_Proxy.h @@ -1,21 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Event Service Framework -// -// = FILENAME -// ESF_Shutdown_Proxy -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Shutdown_Proxy.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ + #ifndef TAO_ESF_SHUTDOWN_PROXY_H #define TAO_ESF_SHUTDOWN_PROXY_H @@ -26,6 +19,7 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/// A worker to invoke the shutdown method of each proxy. template<class PROXY> class TAO_ESF_Shutdown_Proxy : public TAO_ESF_Worker<PROXY> { diff --git a/TAO/orbsvcs/orbsvcs/ESF/ESF_Worker.h b/TAO/orbsvcs/orbsvcs/ESF/ESF_Worker.h index f3001e69aef..06e766a48e6 100644 --- a/TAO/orbsvcs/orbsvcs/ESF/ESF_Worker.h +++ b/TAO/orbsvcs/orbsvcs/ESF/ESF_Worker.h @@ -1,21 +1,13 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// ESF_Worker -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file ESF_Worker.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_ESF_WORKER_H #define TAO_ESF_WORKER_H @@ -26,12 +18,22 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/// Define the interface for the Worker objects +/** + * The Event Service Framework uses Worker classes to iterate over + * collections of proxies. + * The followin class defines the worker interface, basically users of + * the framework implement a worker object and pass it to one + * collection. The collection invokes the worker for each element the + * colection contains. + */ template<class Object> class TAO_ESF_Worker { public: virtual ~TAO_ESF_Worker (void); + /// Callback interface. virtual void work (Object *object, CORBA::Environment &ACE_TRY_ENV) = 0; }; diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_And_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_And_Filter.h index 3ac480fcbb3..9457729412e 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_And_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_And_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_And_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_And_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_AND_FILTER_H #define TAO_EC_AND_FILTER_H @@ -32,26 +22,27 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_And_Filter + * + * @brief The 'logical and' filter. + * + * This filter has a set of children (fixed at creation time), + * only if all the children accept an event it does so too. + * + * <H2>Memory Management</H2> + * It assumes ownership of the children. + */ class TAO_RTEvent_Export TAO_EC_And_Filter : public TAO_EC_Filter { - // = TITLE - // The 'logical and' filter. - // - // = DESCRIPTION - // This filter has a set of children (fixed at creation time), - // only if all the children accept an event it does so too. - // - // = MEMORY MANAGMENT - // It assumes ownership of the children. - // public: + /// Constructor. It assumes ownership of both the array and the + /// children. TAO_EC_And_Filter (TAO_EC_Filter* children[], size_t n); - // Constructor. It assumes ownership of both the array and the - // children. + /// Destructor virtual ~TAO_EC_And_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -86,11 +77,11 @@ private: (const TAO_EC_And_Filter&)) private: + /// The children TAO_EC_Filter** children_; - // The children + /// The number of children. size_t n_; - // The number of children. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Factory.h b/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Factory.h index 61f565fcafe..f805e47c4ac 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Factory.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Factory.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Basic_Factory -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Basic_Factory.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_BASIC_FACTORY_H #define TAO_EC_BASIC_FACTORY_H @@ -32,27 +22,27 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Basic_Factory + * + * @brief The factory for a simple event channel. + * + * An slightly more advanced configuration than the + * EC_Null_Factory, this class configure an event channel that can + * support filtering and correlation. Still dispatching is not + * prioritized and all the filtering is done at the consumer level. + * A fixed POA is used for servant activation. + * This object creates a single instance of the Supplier + * + */ class TAO_RTEvent_Export TAO_EC_Basic_Factory : public TAO_EC_Factory { - // = TITLE - // The factory for a simple event channel. - // - // = DESCRIPTION - // An slightly more advanced configuration than the - // EC_Null_Factory, this class configure an event channel that can - // support filtering and correlation. Still dispatching is not - // prioritized and all the filtering is done at the consumer level. - // A fixed POA is used for servant activation. - // This object creates a single instance of the Supplier - // - // = MEMORY MANAGMENT - // public: + /// Constructor TAO_EC_Basic_Factory (void); - // Constructor + /// destructor... virtual ~TAO_EC_Basic_Factory (void); - // destructor... // = The EC_Factory methods virtual TAO_EC_Dispatching* diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Filter_Builder.h b/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Filter_Builder.h index 5168d75d823..ea95c0f36e6 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Filter_Builder.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Basic_Filter_Builder.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Basic_Filter_Builder -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Basic_Filter_Builder.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_BASIC_FILTER_BUILDER_H #define TAO_EC_BASIC_FILTER_BUILDER_H @@ -36,22 +26,23 @@ class TAO_EC_Filter; class TAO_EC_Event_Channel; +/** + * @class TAO_EC_Basic_Filter_Builder + * + * @brief Implement a builder for the fundamental filters. + * + * The basic filtering mechanisms in the Event channel + * (source/type based filtering + disjunctions and conjunctions) + * are constructed using this class. + */ class TAO_RTEvent_Export TAO_EC_Basic_Filter_Builder : public TAO_EC_Filter_Builder { - // = TITLE - // Implement a builder for the fundamental filters. - // - // = DESCRIPTION - // The basic filtering mechanisms in the Event channel - // (source/type based filtering + disjunctions and conjunctions) - // are constructed using this class. - // public: + /// constructor. TAO_EC_Basic_Filter_Builder (TAO_EC_Event_Channel* ec); - // constructor. + /// destructor... virtual ~TAO_EC_Basic_Filter_Builder (void); - // destructor... // = The TAO_EC_Filter_Builder methods... TAO_EC_Filter* build (TAO_EC_ProxyPushSupplier *supplier, @@ -59,19 +50,19 @@ public: CORBA::Environment &env) const; private: + /// Recursively build the filter tree. TAO_EC_Filter* recursive_build (TAO_EC_ProxyPushSupplier *supplier, RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::ULong& pos) const; - // Recursively build the filter tree. + /// Count the number of children of the current node, i.e. until a + /// conjunction or disjunction starts. CORBA::ULong count_children (RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::ULong pos) const; - // Count the number of children of the current node, i.e. until a - // conjunction or disjunction starts. private: + /// The event channel. TAO_EC_Event_Channel* event_channel_; - // The event channel. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Bitmask_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Bitmask_Filter.h index f5d7c02160d..d61d5423a5f 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Bitmask_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Bitmask_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Bitmask_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Bitmask_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_BITMASK_FILTER_H #define TAO_EC_BITMASK_FILTER_H @@ -33,40 +23,43 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Bitmask_Filter + * + * @brief The bitmask filter. + * + * This filter quickly rejects events that do not match a given + * bitmask. + * If the event is not rejected based on the mask then the child + * is consulted to finally accept or reject the event. + * When composed with the Null_Filter it accepts any events that + * satisfy: + * (event.header.type & type_mask) != 0 + * && (event.header.type & source_mask) != 0 + * + * <H2>Memory Management</H2> + * It assumes ownership of the child. + */ class TAO_RTEvent_Export TAO_EC_Bitmask_Filter : public TAO_EC_Filter { - // = TITLE - // The bitmask filter. - // - // = DESCRIPTION - // This filter quickly rejects events that do not match a given - // bitmask. - // If the event is not rejected based on the mask then the child - // is consulted to finally accept or reject the event. - // When composed with the Null_Filter it accepts any events that - // satisfy: - // (event.header.type & type_mask) != 0 - // && (event.header.type & source_mask) != 0 - // - // = MEMORY MANAGMENT - // It assumes ownership of the child. - // public: + /** + * Constructor. + * Events that do not satisfy: + * + * (e.header.source & source_mask) != 0 && + * (e.header.type & type_mask) != 0 + * + * are immediately rejected, other events are recursively tested + * using the child node. + * It assumes ownership of the child. + */ TAO_EC_Bitmask_Filter (CORBA::ULong source_mask, CORBA::ULong type_mask, TAO_EC_Filter* child); - // Constructor. - // Events that do not satisfy: - // - // (e.header.source & source_mask) != 0 && - // (e.header.type & type_mask) != 0 - // - // are immediately rejected, other events are recursively tested - // using the child node. - // It assumes ownership of the child. + /// Destructor virtual ~TAO_EC_Bitmask_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -99,12 +92,12 @@ private: (const TAO_EC_Bitmask_Filter&)) private: + /// The bitmasks CORBA::ULong source_mask_; CORBA::ULong type_mask_; - // The bitmasks + /// The children TAO_EC_Filter* child_; - // The children }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Busy_Lock.h b/TAO/orbsvcs/orbsvcs/Event/EC_Busy_Lock.h index 8dbb7dc5187..05332ec6543 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Busy_Lock.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Busy_Lock.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_ConsumerAdmin -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_ConsumerAdmin.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_BUSY_LOCK_H #define TAO_EC_BUSY_LOCK_H @@ -36,8 +26,8 @@ template<class Adaptee> class TAO_EC_Busy_Lock_Adapter { public: + /// Constructor TAO_EC_Busy_Lock_Adapter (Adaptee* adaptee); - // Constructor // = The ACE_Lock methods, please check $ACE_ROOT/ace/Synch.h for // details. diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Conjunction_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Conjunction_Filter.h index 31aa16deff3..cd0f95e0f28 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Conjunction_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Conjunction_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Conjunction_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Conjunction_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_CONJUNCTION_FILTER_H #define TAO_EC_CONJUNCTION_FILTER_H @@ -33,27 +23,28 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Conjunction_Filter + * + * @brief The conjunction filter. + * + * This filter waits until each one of its children has accepted + * at least one event. Only in that case it accepts and publishes + * the sequence formed by all the children events. + * + * <H2>Memory Management</H2> + * It assumes ownership of the children. + */ class TAO_RTEvent_Export TAO_EC_Conjunction_Filter : public TAO_EC_Filter { - // = TITLE - // The conjunction filter. - // - // = DESCRIPTION - // This filter waits until each one of its children has accepted - // at least one event. Only in that case it accepts and publishes - // the sequence formed by all the children events. - // - // = MEMORY MANAGMENT - // It assumes ownership of the children. - // public: + /// Constructor. It assumes ownership of both the array and the + /// children. TAO_EC_Conjunction_Filter (TAO_EC_Filter* children[], size_t n); - // Constructor. It assumes ownership of both the array and the - // children. + /// Destructor virtual ~TAO_EC_Conjunction_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -82,8 +73,8 @@ public: typedef unsigned int Word; private: + /// Determine if all the children have received their events. int all_received (void) const; - // Determine if all the children have received their events. ACE_UNIMPLEMENTED_FUNC (TAO_EC_Conjunction_Filter (const TAO_EC_Conjunction_Filter&)) @@ -91,23 +82,25 @@ private: (const TAO_EC_Conjunction_Filter&)) private: + /// The children TAO_EC_Filter** children_; - // The children + /// The number of children. size_t n_; - // The number of children. + /// The event we send up (once all the children have pushed theirs). RtecEventComm::EventSet event_; - // The event we send up (once all the children have pushed theirs). + /** + * The number of words in the bit vector + * The bit vector to keep track of the children that have received + * their events. + */ size_t nwords_; - // The number of words in the bit vector Word* bitvec_; - // The bit vector to keep track of the children that have received - // their events. + /// The current child in the iteration, used in the push() method... ChildrenIterator current_child_; - // The current child in the iteration, used in the push() method... }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerAdmin.h b/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerAdmin.h index 65ec05bd6e0..6fd0c393669 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerAdmin.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerAdmin.h @@ -1,25 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_ConsumerAdmin -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// ============================================================================ +/** + * @file EC_ConsumerAdmin.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_CONSUMERADMIN_H #define TAO_EC_CONSUMERADMIN_H @@ -37,36 +28,35 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushConsumer; + +/** + * @class TAO_EC_ConsumerAdmin + * + * @brief Implements the ConsumerAdmin interface, i.e. the factory for + * TAO_EC_ProxyPushSupplier objects. + * + * <H2> Memory Management</H2> + * It does not assume ownership of the TAO_EC_Event_Channel object; + * but it *does* assume ownership of the TAO_EC_ProxyPushSupplier_Set + * object. + * + * <H2>Locking</H2> + * No provisions for locking, access must be serialized externally. + */ class TAO_RTEvent_Export TAO_EC_ConsumerAdmin : public POA_RtecEventChannelAdmin::ConsumerAdmin , public TAO_ESF_Peer_Admin<TAO_EC_Event_Channel,TAO_EC_ProxyPushSupplier,RtecEventChannelAdmin::ProxyPushSupplier,TAO_EC_ProxyPushConsumer> { - // = TITLE - // ConsumerAdmin - // - // = DESCRIPTION - // Implements the ConsumerAdmin interface, i.e. the factory for - // ProxyPushSupplier objects. - // - // = MEMORY MANAGMENT - // It does not assume ownership of the TAO_EC_Event_Channel - // object; but it *does* assume ownership of the - // TAO_EC_ProxyPushSupplier_Set object. - // - // = LOCKING - // No provisions for locking, access must be serialized - // externally. - // - // = TODO - // public: + /** + * constructor. If <supplier_set> is nil then it builds one using + * the <event_channel> argument. + * In any case it assumes ownership. + */ TAO_EC_ConsumerAdmin (TAO_EC_Event_Channel* event_channel); - // constructor. If <supplier_set> is nil then it builds one using - // the <event_channel> argument. - // In any case it assumes ownership. + /// destructor... virtual ~TAO_EC_ConsumerAdmin (void); - // destructor... // = The RtecEventChannelAdmin::ConsumerAdmin methods... virtual RtecEventChannelAdmin::ProxyPushSupplier_ptr @@ -77,8 +67,8 @@ public: virtual PortableServer::POA_ptr _default_POA (CORBA::Environment& env); private: + /// Store the default POA. PortableServer::POA_var default_POA_; - // Store the default POA. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerControl.h b/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerControl.h index 9ec6e84b618..d3283c498a4 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerControl.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_ConsumerControl.h @@ -1,21 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_ConsumerControl -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// More details can be found in: -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file EC_ConsumerControl.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_CONSUMERCONTROL_H #define TAO_EC_CONSUMERCONTROL_H @@ -31,45 +26,42 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushSupplier; +/** + * @class TAO_EC_ConsumerControl + * + * @brief ConsumerControl + * + * Defines the interface for the consumer control strategy. + * This strategy handles misbehaving or failing consumers. + */ class TAO_RTEvent_Export TAO_EC_ConsumerControl { - // = TITLE - // ConsumerControl - // - // = DESCRIPTION - // Defines the interface for the consumer control strategy. - // This strategy handles misbehaving or failing consumers. - // - // = MEMORY MANAGMENT - // - // = LOCKING - // - // = TODO - // public: + /// Constructor. It does not assume ownership of the <event_channel> + /// parameter. TAO_EC_ConsumerControl (void); - // Constructor. It does not assume ownership of the <event_channel> - // parameter. + /// destructor... virtual ~TAO_EC_ConsumerControl (void); - // destructor... + /// Activate any internal threads or timers used to poll the state of + /// the consumers virtual int activate (void); virtual int shutdown (void); - // Activate any internal threads or timers used to poll the state of - // the consumers + /** + * When pushing an event to the consumer a CORBA::OBJECT_NOT_EXIST + * exception was raised. The only interpretation is that the object + * has been destroyed. The strategy has to (at the very least), + * reclaim all the resources attached to that object. + */ virtual void consumer_not_exist (TAO_EC_ProxyPushSupplier *proxy, CORBA::Environment &); - // When pushing an event to the consumer a CORBA::OBJECT_NOT_EXIST - // exception was raised. The only interpretation is that the object - // has been destroyed. The strategy has to (at the very least), - // reclaim all the resources attached to that object. + /// Some system exception was rasied while trying to push an event. virtual void system_exception (TAO_EC_ProxyPushSupplier *proxy, CORBA::SystemException &, CORBA::Environment &); - // Some system exception was rasied while trying to push an event. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Default_Factory.h b/TAO/orbsvcs/orbsvcs/Event/EC_Default_Factory.h index dba7bf0258d..6aa9773358d 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Default_Factory.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Default_Factory.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Default_Factory -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Default_Factory.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_DEFAULT_FACTORY_H #define TAO_EC_DEFAULT_FACTORY_H @@ -34,30 +24,29 @@ #include "EC_Defaults.h" +/** + * @class TAO_EC_Default_Factory + * + * @brief A generic factory for EC experimentation. + * + * This class allows the user to experiment with different EC + * configurations. Using a command-line like interface the user + * can specify which strategies will this factory generate. + * Since the class can be dynamically loaded the strategies can be + * set in the service configurator file. + */ class TAO_RTEvent_Export TAO_EC_Default_Factory : public TAO_EC_Factory { - // = TITLE - // A generic factory for EC experimentation. - // - // = DESCRIPTION - // This class allows the user to experiment with different EC - // configurations. Using a command-line like interface the user - // can specify which strategies will this factory generate. - // Since the class can be dynamically loaded the strategies can be - // set in the service configurator file. - // - // = MEMORY MANAGMENT - // public: + /// Constructor TAO_EC_Default_Factory (void); - // Constructor + /// destructor... virtual ~TAO_EC_Default_Factory (void); - // destructor... + /// Helper function to register the default factory into the service + /// configurator. static int init_svcs (void); - // Helper function to register the default factory into the service - // configurator. // = The Service_Object entry points virtual int init (int argc, char* argv[]); @@ -128,6 +117,7 @@ public: destroy_supplier_control (TAO_EC_SupplierControl*); protected: + /// Several flags to control the kind of object created. int dispatching_; int filtering_; int supplier_filtering_; @@ -138,25 +128,24 @@ protected: int supplier_collection_; int consumer_lock_; int supplier_lock_; - // Several flags to control the kind of object created. + /// The MT dispatching priority has several arguments that could be + /// controlled here... int dispatching_threads_; int dispatching_threads_flags_; int dispatching_threads_priority_; int dispatching_threads_force_active_; - // The MT dispatching priority has several arguments that could be - // controlled here... + /// Use this ORB to locate global resources. const char *orbid_; - // Use this ORB to locate global resources. + /// The consumer and supplier control policies. int consumer_control_; int supplier_control_; - // The consumer and supplier control policies. + /// The consumer and supplier control periods in usecs int consumer_control_period_; int supplier_control_period_; - // The consumer and supplier control periods in usecs }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Defaults.h b/TAO/orbsvcs/orbsvcs/Event/EC_Defaults.h index a585189b939..d34deb58353 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Defaults.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Defaults.h @@ -1,30 +1,19 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Defaults -// -// = DESCRIPTION -// In this file we set the compile time defaults for the event -// channel. -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Defaults.h + * + * $Id$ + * + * In this file we set the compile time defaults for the event + * channel. + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_DEFAULTS_H #define TAO_EC_DEFAULTS_H diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Disjunction_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Disjunction_Filter.h index 94d597e3d46..b5391bd9283 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Disjunction_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Disjunction_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Disjunction_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Disjunction_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_DISJUNCTION_FILTER_H #define TAO_EC_DISJUNCTION_FILTER_H @@ -32,26 +22,27 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Disjunction_Filter + * + * @brief The disjunction filter. + * + * This filter has a set of children (fixed at creation time), if + * any of the children accepts an event then it also does. + * + * <H2>Memory Management</H2> + * It assumes ownership of the children. + */ class TAO_RTEvent_Export TAO_EC_Disjunction_Filter : public TAO_EC_Filter { - // = TITLE - // The disjunction filter. - // - // = DESCRIPTION - // This filter has a set of children (fixed at creation time), if - // any of the children accepts an event then it also does. - // - // = MEMORY MANAGMENT - // It assumes ownership of the children. - // public: + /// Constructor. It assumes ownership of both the array and the + /// children. TAO_EC_Disjunction_Filter (TAO_EC_Filter* children[], size_t n); - // Constructor. It assumes ownership of both the array and the - // children. + /// Destructor virtual ~TAO_EC_Disjunction_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in @@ -85,11 +76,11 @@ private: (const TAO_EC_Disjunction_Filter&)) private: + /// The children TAO_EC_Filter** children_; - // The children + /// The number of children. size_t n_; - // The number of children. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching.h b/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching.h index 6660b24571d..69c41ac6137 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Dispatching -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Dispatching.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_DISPATCHING_H #define TAO_EC_DISPATCHING_H @@ -36,32 +26,40 @@ class TAO_EC_QOS_Info; class TAO_EC_ProxyPushSupplier; +/** + * @class TAO_EC_Dispatching + * + * @brief Abstract base class for the dispatching strategies. + * + * The dispatching strategies. + * The EC may be configured with different dispatching strategies, + * for instance, it can use a pool of threads to dispatch the + * events, or a set of queues with threads at different priorities + * for each queue or can simply push the event to the consumer in + * FIFO order. + */ class TAO_RTEvent_Export TAO_EC_Dispatching { - // = TITLE - // Abstract base class for the dispatching strategies. - // - // = DESCRIPTION - // The dispatching strategies. - // The EC may be configured with different dispatching strategies, - // for instance, it can use a pool of threads to dispatch the - // events, or a set of queues with threads at different priorities - // for each queue or can simply push the event to the consumer in - // FIFO order. - // public: + /// destructor... virtual ~TAO_EC_Dispatching (void); - // destructor... + /// Initialize all the data structures, activate any internal threads, + /// etc. virtual void activate (void) = 0; - // Initialize all the data structures, activate any internal threads, - // etc. + /** + * Deactivate any internal threads and cleanup internal data + * structures, it should only return once the threads have finished + * their jobs. + */ virtual void shutdown (void) = 0; - // Deactivate any internal threads and cleanup internal data - // structures, it should only return once the threads have finished - // their jobs. + /** + * The consumer represented by <proxy> should receive <event>. + * It can use the information in <qos_info> to determine the event + * priority (among other things). + */ virtual void push (TAO_EC_ProxyPushSupplier *proxy, RtecEventComm::PushConsumer_ptr consumer, const RtecEventComm::EventSet &event, @@ -72,26 +70,24 @@ public: RtecEventComm::EventSet &event, TAO_EC_QOS_Info &qos_info, CORBA::Environment &env = TAO_default_environment ()) = 0; - // The consumer represented by <proxy> should receive <event>. - // It can use the information in <qos_info> to determine the event - // priority (among other things). }; // **************************************************************** +/** + * @class TAO_EC_Reactive_Dispatching + * + * @brief Dispatch using the caller thread. + * + * The events are dispatched in FIFO ordering, using the invoking + * thread to push the event to the consumer. + */ class TAO_RTEvent_Export TAO_EC_Reactive_Dispatching : public TAO_EC_Dispatching { - // = TITLE - // Dispatch using the caller thread. - // - // = DESCRIPTION - // The events are dispatched in FIFO ordering, using the invoking - // thread to push the event to the consumer. - // public: + /// The scheduler is used to find the range of priorities and similar + /// info. TAO_EC_Reactive_Dispatching (void); - // The scheduler is used to find the range of priorities and similar - // info. // = The EC_Dispatching methods. virtual void activate (void); diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching_Task.h b/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching_Task.h index ab826954cbb..a84aa3995fc 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching_Task.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Dispatching_Task.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Dispatching_Task -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Dispatching_Task.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_DISPATCHING_TASK_H #define TAO_EC_DISPATCHING_TASK_H @@ -50,20 +40,21 @@ protected: virtual int is_full_i (void); }; +/** + * @class TAO_EC_Dispatching_Task + * + * @brief Implement the dispatching queues for FIFO and Priority + * dispatching. + * + */ class TAO_RTEvent_Export TAO_EC_Dispatching_Task : public ACE_Task<ACE_SYNCH> { - // = TITLE - // Implement the dispatching queues for FIFO and Priority - // dispatching. - // - // = DESCRIPTION - // public: + /// Constructor TAO_EC_Dispatching_Task (ACE_Thread_Manager* thr_manager = 0); - // Constructor + /// Process the events in the queue. virtual int svc (void); - // Process the events in the queue. virtual void push (TAO_EC_ProxyPushSupplier *proxy, RtecEventComm::PushConsumer_ptr consumer, @@ -71,14 +62,14 @@ public: CORBA::Environment &env); private: + /// An per-task allocator ACE_Allocator *allocator_; - // An per-task allocator + /// Helper data structure to minimize memory allocations... ACE_Locked_Data_Block<ACE_Lock_Adapter<ACE_SYNCH_MUTEX> > data_block_; - // Helper data structure to minimize memory allocations... + /// The queue TAO_EC_Queue the_queue_; - // The queue }; // **************************************************************** @@ -86,18 +77,18 @@ private: class TAO_RTEvent_Export TAO_EC_Dispatch_Command : public ACE_Message_Block { public: + /// Constructor, it will allocate its own data block TAO_EC_Dispatch_Command (ACE_Allocator *mb_allocator = 0); - // Constructor, it will allocate its own data block + /// Constructor, it assumes ownership of the data block TAO_EC_Dispatch_Command (ACE_Data_Block*, ACE_Allocator *mb_allocator = 0); - // Constructor, it assumes ownership of the data block + /// Destructor virtual ~TAO_EC_Dispatch_Command (void); - // Destructor + /// Command callback virtual int execute (CORBA::Environment&) = 0; - // Command callback }; // **************************************************************** @@ -105,11 +96,11 @@ public: class TAO_RTEvent_Export TAO_EC_Shutdown_Task_Command : public TAO_EC_Dispatch_Command { public: + /// Constructor TAO_EC_Shutdown_Task_Command (ACE_Allocator *mb_allocator = 0); - // Constructor + /// Command callback virtual int execute (CORBA::Environment&); - // Command callback }; // **************************************************************** @@ -117,28 +108,28 @@ public: class TAO_RTEvent_Export TAO_EC_Push_Command : public TAO_EC_Dispatch_Command { public: + /// Constructor TAO_EC_Push_Command (TAO_EC_ProxyPushSupplier* proxy, RtecEventComm::PushConsumer_ptr consumer, RtecEventComm::EventSet& event, ACE_Data_Block* data_block, ACE_Allocator *mb_allocator); - // Constructor + /// Destructor virtual ~TAO_EC_Push_Command (void); - // Destructor + /// Command callback virtual int execute (CORBA::Environment&); - // Command callback private: + /// The proxy TAO_EC_ProxyPushSupplier* proxy_; - // The proxy + /// The consumer connected to the proxy when the event was pushed. RtecEventComm::PushConsumer_var consumer_; - // The consumer connected to the proxy when the event was pushed. + /// The event RtecEventComm::EventSet event_; - // The event }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Event_Channel.h b/TAO/orbsvcs/orbsvcs/Event/EC_Event_Channel.h index 270c25e0d19..fcfa8648742 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Event_Channel.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Event_Channel.h @@ -1,27 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Event_Channel -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = DESCRIPTION -// A new implementation of the Real Time Event Services. -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Event_Channel.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_EVENT_CHANNEL_H #define TAO_EC_EVENT_CHANNEL_H @@ -36,211 +25,221 @@ #include "EC_Defaults.h" #include "orbsvcs/RtecEventChannelAdminS.h" +/** + * @class TAO_EC_Event_Channel_Attributes + * + * @brief Defines the construction time attributes for the Event + * Channel. + * + * The event channel implementation is controlled by two + * mechanisms: + * The EC_Factory that provides the strategies for the EC + * implementation. + * The EC attributes that define constants and values required + * by the EC construction. + * This class encapsulates those constants and values, providing + * an easy mechanism to extend the attributes without requiring + * changes in the EC constructor. + */ class TAO_RTEvent_Export TAO_EC_Event_Channel_Attributes { - // = TITLE - // Defines the construction time attributes for the Event - // Channel. - // - // = DESCRIPTION - // The event channel implementation is controlled by two - // mechanisms: - // The EC_Factory that provides the strategies for the EC - // implementation. - // The EC attributes that define constants and values required - // by the EC construction. - // This class encapsulates those constants and values, providing - // an easy mechanism to extend the attributes without requiring - // changes in the EC constructor. - // public: + /** + * The basic constructor. + * The attributes listed as arguments are *required* by the EC, and + * no appropiate defaults are available for them. + */ TAO_EC_Event_Channel_Attributes (PortableServer::POA_ptr supplier_poa, PortableServer::POA_ptr consumer_poa); - // The basic constructor. - // The attributes listed as arguments are *required* by the EC, and - // no appropiate defaults are available for them. // Most fields are public, there is no need to protect them, in fact // the user should be able to set any values she wants. + /// Can consumers or suppliers invoke connect_push_* multiple times? int consumer_reconnect; int supplier_reconnect; - // Can consumers or suppliers invoke connect_push_* multiple times? + /** + * It not zero the event channel will send disconnect callbacks when + * a disconnect method is called on a Proxy. In other words, if a + * consumer calls disconnect_push_supplier() on its proxy the EC + * will invoke disconnect_push_consumer() on the consumer. A + * similar thing is done for suppliers. + * It is a matter of debate what the spec requires for the regular + * event service. + */ int disconnect_callbacks; - // It not zero the event channel will send disconnect callbacks when - // a disconnect method is called on a Proxy. In other words, if a - // consumer calls disconnect_push_supplier() on its proxy the EC - // will invoke disconnect_push_consumer() on the consumer. A - // similar thing is done for suppliers. - // It is a matter of debate what the spec requires for the regular - // event service. + /// Flags for the Consumer Admin int busy_hwm; int max_write_delay; - // Flags for the Consumer Admin + /** + * The scheduling service that we will use with this event channel. + * Notice that this is optional and will only take effect if the EC + * is configured with the right filtering strategies. + */ CORBA::Object_ptr scheduler; - // The scheduling service that we will use with this event channel. - // Notice that this is optional and will only take effect if the EC - // is configured with the right filtering strategies. private: + /// Only the EC can read the private fields. friend class TAO_EC_Event_Channel; - // Only the EC can read the private fields. + /// The POAs PortableServer::POA_ptr supplier_poa; PortableServer::POA_ptr consumer_poa; - // The POAs }; +/** + * @class TAO_EC_Event_Channel + * + * @brief The RtecEventChannelAdmin::EventChannel implementation. + * + * This class is the Mediator between all the classes in the EC + * implementation, its main task is to redirect the messages to + * the right components, to hold and manage the lifetime of the + * long lived objects (Timer_Module, SupplierAdmin, + * ConsumerAdmin and Dispatching) and to provide a simpler + * interface to the EC_Factory. + */ class TAO_RTEvent_Export TAO_EC_Event_Channel : public POA_RtecEventChannelAdmin::EventChannel { - // = TITLE - // The RtecEventChannelAdmin::EventChannel implementation. - // - // = DESCRIPTION - // This class is the Mediator between all the classes in the EC - // implementation, its main task is to redirect the messages to - // the right components, to hold and manage the lifetime of the - // long lived objects (Timer_Module, SupplierAdmin, - // ConsumerAdmin and Dispatching) and to provide a simpler - // interface to the EC_Factory. - // public: + /** + * constructor + * If <own_factory> is not 0 it assumes ownership of the factory. + * If the factory is <nil> it uses the Service_Configurator to load + * the Factory, if not found it uses TAO_EC_Default_Resource_Factory + */ TAO_EC_Event_Channel (const TAO_EC_Event_Channel_Attributes& attributes, TAO_EC_Factory* factory = 0, int own_factory = 0); - // constructor - // If <own_factory> is not 0 it assumes ownership of the factory. - // If the factory is <nil> it uses the Service_Configurator to load - // the Factory, if not found it uses TAO_EC_Default_Resource_Factory + /// destructor virtual ~TAO_EC_Event_Channel (void); - // destructor + /// Start the internal threads (if any), etc. + /// After this call the EC can be used. virtual void activate (CORBA::Environment &env = TAO_default_environment ()); - // Start the internal threads (if any), etc. - // After this call the EC can be used. + /// Shutdown any internal threads, cleanup all the internal + /// structures, flush all the messages, etc. virtual void shutdown (CORBA::Environment &env = TAO_default_environment ()); - // Shutdown any internal threads, cleanup all the internal - // structures, flush all the messages, etc. + /// Access the dispatching module.... TAO_EC_Dispatching* dispatching (void) const; - // Access the dispatching module.... + /// Access the filter builder.... TAO_EC_Filter_Builder* filter_builder (void) const; - // Access the filter builder.... + /// Access the filter builder.... TAO_EC_Supplier_Filter_Builder* supplier_filter_builder (void) const; - // Access the filter builder.... + /// Access the consumer admin implementation, useful for controlling + /// the activation... TAO_EC_ConsumerAdmin* consumer_admin (void) const; - // Access the consumer admin implementation, useful for controlling - // the activation... + /// Access the supplier admin implementation, useful for controlling + /// the activation... TAO_EC_SupplierAdmin* supplier_admin (void) const; - // Access the supplier admin implementation, useful for controlling - // the activation... + /// Access the timer module... TAO_EC_Timeout_Generator* timeout_generator (void) const; - // Access the timer module... + /// Access the scheduling strategy TAO_EC_Scheduling_Strategy* scheduling_strategy (void) const; - // Access the scheduling strategy + /// Access the client control strategies. TAO_EC_ConsumerControl *consumer_control (void) const; TAO_EC_SupplierControl *supplier_control (void) const; - // Access the client control strategies. // = The factory methods, they delegate on the EC_Factory. + /// Create and destroy a ProxyPushSupplier void create_proxy (TAO_EC_ProxyPushSupplier*&); void destroy_proxy (TAO_EC_ProxyPushSupplier*); - // Create and destroy a ProxyPushSupplier + /// Create and destroy a ProxyPushConsumer void create_proxy (TAO_EC_ProxyPushConsumer*&); void destroy_proxy (TAO_EC_ProxyPushConsumer*); - // Create and destroy a ProxyPushConsumer + /// Create and destroy a the collections used to store + /// ProxyPushSuppliers void create_proxy_collection (TAO_EC_ProxyPushSupplier_Collection*&); void destroy_proxy_collection (TAO_EC_ProxyPushSupplier_Collection*); - // Create and destroy a the collections used to store - // ProxyPushSuppliers + /// Create and destroy a the collections used to store + /// ProxyPushConsumers void create_proxy_collection (TAO_EC_ProxyPushConsumer_Collection*&); void destroy_proxy_collection (TAO_EC_ProxyPushConsumer_Collection*); - // Create and destroy a the collections used to store - // ProxyPushConsumers + /// Access the supplier and consumer POAs from the factory. PortableServer::POA_ptr supplier_poa (void); PortableServer::POA_ptr consumer_poa (void); - // Access the supplier and consumer POAs from the factory. + /// Locking strategies for the ProxyPushConsumer and + /// ProxyPushSupplier objects ACE_Lock* create_consumer_lock (void); void destroy_consumer_lock (ACE_Lock*); ACE_Lock* create_supplier_lock (void); void destroy_supplier_lock (ACE_Lock*); - // Locking strategies for the ProxyPushConsumer and - // ProxyPushSupplier objects + /// Used to inform the EC that a Consumer has connected or + /// disconnected from it. virtual void connected (TAO_EC_ProxyPushConsumer*, CORBA::Environment&); virtual void reconnected (TAO_EC_ProxyPushConsumer*, CORBA::Environment&); virtual void disconnected (TAO_EC_ProxyPushConsumer*, CORBA::Environment&); - // Used to inform the EC that a Consumer has connected or - // disconnected from it. + /// Used to inform the EC that a Supplier has connected or + /// disconnected from it. virtual void connected (TAO_EC_ProxyPushSupplier*, CORBA::Environment&); virtual void reconnected (TAO_EC_ProxyPushSupplier*, CORBA::Environment&); virtual void disconnected (TAO_EC_ProxyPushSupplier*, CORBA::Environment&); - // Used to inform the EC that a Supplier has connected or - // disconnected from it. // Simple flags to control the EC behavior, set by the application // at construction time. + /// Can the consumers reconnect to the EC? int consumer_reconnect (void) const; - // Can the consumers reconnect to the EC? + /// Can the suppliers reconnect to the EC? int supplier_reconnect (void) const; - // Can the suppliers reconnect to the EC? + /// Should we send callback disconnect messages when a proxy is + /// disconnected by the client int disconnect_callbacks (void) const; - // Should we send callback disconnect messages when a proxy is - // disconnected by the client + /// Obtain the scheduler, the user must release CORBA::Object_ptr scheduler (void); - // Obtain the scheduler, the user must release + /// Control the concurrency of the delayed connect/disconnect + /// operations. int busy_hwm (void) const; int max_write_delay (void) const; - // Control the concurrency of the delayed connect/disconnect - // operations. // = The RtecEventChannelAdmin::EventChannel methods... + /// The default implementation is: + /// this->consumer_admin ()->_this (env); virtual RtecEventChannelAdmin::ConsumerAdmin_ptr for_consumers (CORBA::Environment& env) ACE_THROW_SPEC ((CORBA::SystemException)); - // The default implementation is: - // this->consumer_admin ()->_this (env); + /// The default implementation is: + /// this->supplier_admin ()->_this (env); virtual RtecEventChannelAdmin::SupplierAdmin_ptr for_suppliers (CORBA::Environment& env) ACE_THROW_SPEC ((CORBA::SystemException)); - // The default implementation is: - // this->supplier_admin ()->_this (env); + /// Commit suicide. virtual void destroy (CORBA::Environment &env) ACE_THROW_SPEC ((CORBA::SystemException)); - // Commit suicide. virtual RtecEventChannelAdmin::Observer_Handle append_observer (RtecEventChannelAdmin::Observer_ptr, @@ -258,62 +257,64 @@ public: RtecEventChannelAdmin::EventChannel::CANT_REMOVE_OBSERVER)); private: + /// The POAs used to activate "supplier-side" and "consumer-side" + /// objects. PortableServer::POA_var supplier_poa_; PortableServer::POA_var consumer_poa_; - // The POAs used to activate "supplier-side" and "consumer-side" - // objects. + /** + * This is the abstract factory that creates all the objects that + * compose an event channel, the event channel simply acts as a + * Mediator among them. + */ TAO_EC_Factory *factory_; - // This is the abstract factory that creates all the objects that - // compose an event channel, the event channel simply acts as a - // Mediator among them. + /// Flag that indicates if we own the factory. int own_factory_; - // Flag that indicates if we own the factory. + /// The dispatching "module" TAO_EC_Dispatching *dispatching_; - // The dispatching "module" + /// The filter builder TAO_EC_Filter_Builder *filter_builder_; - // The filter builder + /// The filter builder for suppliers TAO_EC_Supplier_Filter_Builder *supplier_filter_builder_; - // The filter builder for suppliers + /// The ConsumerAdmin implementation TAO_EC_ConsumerAdmin *consumer_admin_; - // The ConsumerAdmin implementation + /// The SupplierAdmin implementation TAO_EC_SupplierAdmin *supplier_admin_; - // The SupplierAdmin implementation + /// The timeout generator TAO_EC_Timeout_Generator *timeout_generator_; - // The timeout generator + /// The observer strategy TAO_EC_ObserverStrategy *observer_strategy_; - // The observer strategy + /// The scheduler (may be nil) CORBA::Object_var scheduler_; - // The scheduler (may be nil) + /// The scheduling strategy TAO_EC_Scheduling_Strategy *scheduling_strategy_; - // The scheduling strategy + /// Consumer/Supplier reconnection flags int consumer_reconnect_; int supplier_reconnect_; - // Consumer/Supplier reconnection flags + /// If not zero we send callbacks when a proxy is disconnected int disconnect_callbacks_; - // If not zero we send callbacks when a proxy is disconnected + /// Control the level of concurrency in the supplier sets with + /// delayed operations int busy_hwm_; int max_write_delay_; - // Control the level of concurrency in the supplier sets with - // delayed operations + /// Strategies to disconnect misbehaving or destroyed consumers and + /// suppliers TAO_EC_ConsumerControl *consumer_control_; TAO_EC_SupplierControl *supplier_control_; - // Strategies to disconnect misbehaving or destroyed consumers and - // suppliers }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Factory.h b/TAO/orbsvcs/orbsvcs/Event/EC_Factory.h index e39e421cd06..ed5a65f0f92 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Factory.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Factory.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Factory -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Factory.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_FACTORY_H #define TAO_EC_FACTORY_H @@ -56,103 +46,106 @@ class TAO_EC_SupplierControl; typedef TAO_ESF_Proxy_Collection<TAO_EC_ProxyPushConsumer> TAO_EC_ProxyPushConsumer_Collection; typedef TAO_ESF_Proxy_Collection<TAO_EC_ProxyPushSupplier> TAO_EC_ProxyPushSupplier_Collection; +/** + * @class TAO_EC_Factory + * + * @brief Abstract base class for the Event Channel components. + * + * Defines the EC_Factory interface. + * + * <H2>Memory Management</H2> + * The objects it creates are owned by this class, the client must + * invoke the corresponding destroy() method to release them. + * Some implementations may require a different instance for the + * EC_Factory for each instance of Event_Channel. + */ class TAO_RTEvent_Export TAO_EC_Factory : public ACE_Service_Object { - // = TITLE - // Abstract base class for the Event Channel components. - // - // = DESCRIPTION - // Defines the EC_Factory interface. - // - // = MEMORY MANAGMENT - // The objects it creates are owned by this class, the client must - // invoke the corresponding destroy() method to release them. - // Some implementations may require a different instance for the - // EC_Factory for each instance of Event_Channel. - // public: + /// destructor... virtual ~TAO_EC_Factory (void); - // destructor... + /// Create and destroy the dispatching module. virtual TAO_EC_Dispatching* create_dispatching (TAO_EC_Event_Channel*) = 0; virtual void destroy_dispatching (TAO_EC_Dispatching*) = 0; - // Create and destroy the dispatching module. + /// Create and destroy the filter builder. virtual TAO_EC_Filter_Builder* create_filter_builder (TAO_EC_Event_Channel*) = 0; virtual void destroy_filter_builder (TAO_EC_Filter_Builder*) = 0; - // Create and destroy the filter builder. + /// Create and destroy the filter builder. virtual TAO_EC_Supplier_Filter_Builder* create_supplier_filter_builder (TAO_EC_Event_Channel*) = 0; virtual void destroy_supplier_filter_builder (TAO_EC_Supplier_Filter_Builder*) = 0; - // Create and destroy the filter builder. + /// Create and destroy the consumer admin implementation. virtual TAO_EC_ConsumerAdmin* create_consumer_admin (TAO_EC_Event_Channel*) = 0; virtual void destroy_consumer_admin (TAO_EC_ConsumerAdmin*) = 0; - // Create and destroy the consumer admin implementation. + /// Create and destroy the supplier admin implementation. virtual TAO_EC_SupplierAdmin* create_supplier_admin (TAO_EC_Event_Channel*) = 0; virtual void destroy_supplier_admin (TAO_EC_SupplierAdmin*) = 0; - // Create and destroy the supplier admin implementation. + /// Create and destroy a ProxyPushSupplier virtual TAO_EC_ProxyPushSupplier* create_proxy_push_supplier (TAO_EC_Event_Channel*) = 0; virtual void destroy_proxy_push_supplier (TAO_EC_ProxyPushSupplier*) = 0; - // Create and destroy a ProxyPushSupplier + /// Create and destroy a ProxyPushConsumer virtual TAO_EC_ProxyPushConsumer* create_proxy_push_consumer (TAO_EC_Event_Channel*) = 0; virtual void destroy_proxy_push_consumer (TAO_EC_ProxyPushConsumer*) = 0; - // Create and destroy a ProxyPushConsumer + /// Create and destroy the timer module. virtual TAO_EC_Timeout_Generator* create_timeout_generator (TAO_EC_Event_Channel*) = 0; virtual void destroy_timeout_generator (TAO_EC_Timeout_Generator*) = 0; - // Create and destroy the timer module. + /// Create and destroy the observer strategy. virtual TAO_EC_ObserverStrategy* create_observer_strategy (TAO_EC_Event_Channel*) = 0; virtual void destroy_observer_strategy (TAO_EC_ObserverStrategy*) = 0; - // Create and destroy the observer strategy. + /// Create and destroy the observer strategy. virtual TAO_EC_Scheduling_Strategy* create_scheduling_strategy (TAO_EC_Event_Channel*) = 0; virtual void destroy_scheduling_strategy (TAO_EC_Scheduling_Strategy*) = 0; - // Create and destroy the observer strategy. + /// Create and destroy a collection of TAO_EC_ProxyPushConsumers virtual TAO_EC_ProxyPushConsumer_Collection* create_proxy_push_consumer_collection (TAO_EC_Event_Channel*) = 0; virtual void destroy_proxy_push_consumer_collection (TAO_EC_ProxyPushConsumer_Collection*) = 0; - // Create and destroy a collection of TAO_EC_ProxyPushConsumers + /// Create and destroy a collection of TAO_EC_ProxyPushSuppliers virtual TAO_EC_ProxyPushSupplier_Collection* create_proxy_push_supplier_collection (TAO_EC_Event_Channel*) = 0; virtual void destroy_proxy_push_supplier_collection (TAO_EC_ProxyPushSupplier_Collection*) = 0; - // Create and destroy a collection of TAO_EC_ProxyPushSuppliers + /// Create and destroy the locking strategies for both + /// ProxyPushConsumers and ProxyPushSuppliers virtual ACE_Lock* create_consumer_lock (void) = 0; virtual void destroy_consumer_lock (ACE_Lock*) = 0; virtual ACE_Lock* create_supplier_lock (void) = 0; virtual void destroy_supplier_lock (ACE_Lock*) = 0; - // Create and destroy the locking strategies for both - // ProxyPushConsumers and ProxyPushSuppliers + /// The ConsumerControl and SupplierControl strategies are used to + /// discard non-existent consumers and suppliers virtual TAO_EC_ConsumerControl* create_consumer_control (TAO_EC_Event_Channel*) = 0; virtual void @@ -161,8 +154,6 @@ public: create_supplier_control (TAO_EC_Event_Channel*) = 0; virtual void destroy_supplier_control (TAO_EC_SupplierControl*) = 0; - // The ConsumerControl and SupplierControl strategies are used to - // discard non-existent consumers and suppliers }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Filter.h index 620e4eaadf9..206ec8cd122 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_FILTER_H #define TAO_EC_FILTER_H @@ -35,140 +25,151 @@ class TAO_EC_QOS_Info; +/** + * @class TAO_EC_Filter + * + * @brief Abstract base class for the filter hierarchy. + * + * The per-consumer filtering mechanisms. + * The EC needs to filter data passed to the consumers, so it can + * correctly satisfy its subscription requirements. + * This filtering can include correlations, sequences, timeouts, + * etc. each consumer can request different filtering criteria. + * Different filtering objects are associated with each consumer, + * the filters are organized in a hierarchical structure, + * corresponding to the subscription "expression" that the events + * must satisfy. + * The hierarchy is constructed using the "Builder" pattern. + * + * <H2>Memory Management</H2> + * It does *not* assume ownership of its parent. + */ class TAO_RTEvent_Export TAO_EC_Filter { - // = TITLE - // Abstract base class for the filter hierarchy. - // - // = DESCRIPTION - // The per-consumer filtering mechanisms. - // The EC needs to filter data passed to the consumers, so it can - // correctly satisfy its subscription requirements. - // This filtering can include correlations, sequences, timeouts, - // etc. each consumer can request different filtering criteria. - // - // Different filtering objects are associated with each consumer, - // the filters are organized in a hierarchical structure, - // corresponding to the subscription "expression" that the events - // must satisfy. - // The hierarchy is constructed using the "Builder" pattern. - // - // = MEMORY MANAGMENT - // It does *not* assume ownership of its parent. - // public: + /// constructor... TAO_EC_Filter (void); - // constructor... + /// destructor... virtual ~TAO_EC_Filter (void); - // destructor... + /// Obtain the parent of this filter. TAO_EC_Filter* parent (void) const; - // Obtain the parent of this filter. + /// Become the parent of <child> void adopt_child (TAO_EC_Filter* child); - // Become the parent of <child> + /// matches two event headers. + /// @todo Should we strategize the algorithm used to match headers? static int matches (const RtecEventComm::EventHeader& rhs, const RtecEventComm::EventHeader& lhs); - // matches two event headers. - // @@ TODO: strategize this... typedef TAO_EC_Filter* value_type; typedef TAO_EC_Filter* const const_value_type; typedef const_value_type* ChildrenIterator; + /** + * STL-like iterators + * Filters follow the Composite pattern. All filters expose the same + * interface as if they all had children, but for simple filters the + * iterators return an empty range. + */ virtual ChildrenIterator begin (void) const; virtual ChildrenIterator end (void) const; virtual int size (void) const; - // STL-like iterators - // Filters follow the Composite pattern. All filters expose the same - // interface as if they all had children, but for simple filters the - // iterators return an empty range. + /** + * Filter this event, returns 1 if the event is accepted, 0 + * otherwise. + * Notice that there are two versions of the method, if the event is + * not const then filter can take ownership of the event. + */ virtual int filter (const RtecEventComm::EventSet& event, TAO_EC_QOS_Info& qos_info, CORBA::Environment& env) = 0; virtual int filter_nocopy (RtecEventComm::EventSet& event, TAO_EC_QOS_Info& qos_info, CORBA::Environment& env) = 0; - // Filter this event, returns 1 if the event is accepted, 0 - // otherwise. - // Notice that there are two versions of the method, if the event is - // not const then filter can take ownership of the event. + /** + * This is called by the children when they accept an event and + * which to pass it up. + * Notice that there are two versions of the method, if the event is + * not const then filter can take ownership of the event. + */ virtual void push (const RtecEventComm::EventSet& event, TAO_EC_QOS_Info& qos_info, CORBA::Environment& env) = 0; virtual void push_nocopy (RtecEventComm::EventSet& event, TAO_EC_QOS_Info& qos_info, CORBA::Environment& env) = 0; - // This is called by the children when they accept an event and - // which to pass it up. - // Notice that there are two versions of the method, if the event is - // not const then filter can take ownership of the event. + /// Clear any saved state, must reset and assume no events have been + /// received. virtual void clear (void) = 0; - // Clear any saved state, must reset and assume no events have been - // received. + /// Returns the maximum size of the events pushed by this filter. virtual CORBA::ULong max_event_size (void) const = 0; - // Returns the maximum size of the events pushed by this filter. + /** + * Returns 0 if an event with that header could never be accepted. + * This can used by the suppliers to filter out consumers that + * couldn't possibly be interested in their events. + * The rt_info and + */ virtual int can_match (const RtecEventComm::EventHeader& header) const = 0; - // Returns 0 if an event with that header could never be accepted. - // This can used by the suppliers to filter out consumers that - // couldn't possibly be interested in their events. - // The rt_info and + /** + * This is used for computing the scheduling dependencies: + * + * Leaf filters check if the header could be matched, similar to the + * can_match() method; if it does they return 1, and 0 otherwise. + * Intermediate nodes always return 0. + * + * This is used to build precise dependencies between the suppliers + * and the leaf of the filters that accept that event. Notice that + * only the nodes doing scheduling recurse through the list, so in + * configurations that do no require scheduling the recursion stops + * fairly soon. + */ virtual int add_dependencies (const RtecEventComm::EventHeader& header, const TAO_EC_QOS_Info& qos_info, CORBA::Environment &ACE_TRY_ENV) = 0; - // This is used for computing the scheduling dependencies: - // - // Leaf filters check if the header could be matched, similar to the - // can_match() method; if it does they return 1, and 0 otherwise. - // Intermediate nodes always return 0. - // - // This is used to build precise dependencies between the suppliers - // and the leaf of the filters that accept that event. Notice that - // only the nodes doing scheduling recurse through the list, so in - // configurations that do no require scheduling the recursion stops - // fairly soon. + /** + * Obtain the QOS information for this filter, the default + * implementation returns an invalid QOS. Only the filters that + * support scheduling information implement this method. + * Returns 0 on success and -1 on failure + */ virtual void get_qos_info (TAO_EC_QOS_Info& qos_info, CORBA::Environment &ACE_TRY_ENV); - // Obtain the QOS information for this filter, the default - // implementation returns an invalid QOS. Only the filters that - // support scheduling information implement this method. - // Returns 0 on success and -1 on failure private: + /// The parent... TAO_EC_Filter* parent_; - // The parent... }; // **************************************************************** +/** + * @class TAO_EC_Null_Filter + * + * @brief A null filter + * + * This filter accepts any kind of event, it is useful for the + * implementation: + * a) Consumers that accept all events + * b) Consumers that trust the filtering done at the Supplier + * layer. + * c) Event Channels that don't do filtering (such as CosEC + * backends) + */ class TAO_RTEvent_Export TAO_EC_Null_Filter : public TAO_EC_Filter { - // = TITLE - // A null filter - // - // = DESCRIPTION - // This filter accepts any kind of event, it is useful for the - // implementation: - // a) Consumers that accept all events - // b) Consumers that trust the filtering done at the Supplier - // layer. - // c) Event Channels that don't do filtering (such as CosEC - // backends) - // - // = MEMORY MANAGMENT - // public: + /// constructor. TAO_EC_Null_Filter (void); - // constructor. // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Filter_Builder.h b/TAO/orbsvcs/orbsvcs/Event/EC_Filter_Builder.h index 842078e7018..eb494ecccae 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Filter_Builder.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Filter_Builder.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Filter_Builder -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Filter_Builder.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_FILTER_BUILDER_H #define TAO_EC_FILTER_BUILDER_H @@ -36,47 +26,48 @@ class TAO_EC_Filter; class TAO_EC_ProxyPushSupplier; +/** + * @class TAO_EC_Filter_Builder + * + * @brief Abstract base class for the filter builders. + * + * The creation of a filter hierarchy is controlled by a + * Filter_Builder. The relationship between TAO_EC_Filter and + * TAO_EC_Filter_Builder follows the "Builder Pattern" (Gamma et + * al.) + */ class TAO_RTEvent_Export TAO_EC_Filter_Builder { - // = TITLE - // Abstract base class for the filter builders. - // - // = DESCRIPTION - // The creation of a filter hierarchy is controlled by a - // Filter_Builder. The relationship between TAO_EC_Filter and - // TAO_EC_Filter_Builder follows the "Builder Pattern" (Gamma et - // al.) - // - // public: + /// destructor... virtual ~TAO_EC_Filter_Builder (void); - // destructor... + /// Create the filter, the caller must assume ownership of the filter + /// returned. virtual TAO_EC_Filter* build (TAO_EC_ProxyPushSupplier *supplier, RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::Environment &ACE_TRY_ENV) const = 0; - // Create the filter, the caller must assume ownership of the filter - // returned. }; // **************************************************************** +/** + * @class TAO_EC_Null_Filter_Builder + * + * @brief A simple implementation of the filter builder. + * + * Simply creates a Null_Filter in every case. + */ class TAO_RTEvent_Export TAO_EC_Null_Filter_Builder : public TAO_EC_Filter_Builder { - // = TITLE - // A simple implementation of the filter builder. - // - // = DESCRIPTION - // Simply creates a Null_Filter in every case. - // public: + /// constructor. TAO_EC_Null_Filter_Builder (void); - // constructor. + /// destructor... virtual ~TAO_EC_Null_Filter_Builder (void); - // destructor... // = The TAO_EC_Filter_Builder methods... TAO_EC_Filter* build (TAO_EC_ProxyPushSupplier *supplier, diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Gateway.h b/TAO/orbsvcs/orbsvcs/Event/EC_Gateway.h index 790be6625b0..615bdd03291 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Gateway.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Gateway.h @@ -1,34 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// TAO services -// -// = FILENAME -// EC_Gateway -// -// = AUTHOR -// Carlos O'Ryan -// -// = DESCRIPTION -// This class can be used to connect two event channels; the class -// connects to a "remote" EC as a consumer, it also connects to the -// <local> EC as a supplier of events, this later EC is usually -// collocated. -// The QoS parameters for both connections must be provided by the -// user. -// To avoid infinite loops of events the Gateway descreases the TTL -// field of the events and will not deliver any events with TTL less -// than or equal to 0. -// -// = TODO -// The class makes an extra copy of the events, we need to -// investigate if closer collaboration with its collocated EC could -// be used to remove that copy. -// -// ============================================================================ +/** + * @file EC_Gateway.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_GATEWAY_H #define TAO_EC_GATEWAY_H @@ -40,95 +22,99 @@ #include "orbsvcs/Channel_Clients.h" #include "ace/Map_Manager.h" +/** + * @class TAO_EC_Gateway + * + * @brief Event Channel Gateway + * + * There are several ways to connect several EC together, for + * instance: + * + A single class can use normal IIOP and connect to one EC as + * a supplier and to another EC as a consumer. + * + A class connects as a consumer and transmit the events using + * multicast, another class receives the multicast messages and + * transform them back into a push() call. + * This is an abstract class to represent all the different + * strategies for EC distribution. + * + */ class TAO_RTEvent_Export TAO_EC_Gateway : public POA_RtecEventChannelAdmin::Observer { - // = TITLE - // Event Channel Gateway - // - // = DESCRIPTION - // There are several ways to connect several EC together, for - // instance: - // + A single class can use normal IIOP and connect to one EC as - // a supplier and to another EC as a consumer. - // + A class connects as a consumer and transmit the events using - // multicast, another class receives the multicast messages and - // transform them back into a push() call. - // - // This is an abstract class to represent all the different - // strategies for EC distribution. - // public: + /// Default constructor. TAO_EC_Gateway (void); - // Default constructor. + /// Destructor virtual ~TAO_EC_Gateway (void); - // Destructor + /// The gateway must disconnect from all the relevant event channels, + /// or any other communication media (such as multicast groups). virtual void close (CORBA::Environment &env = TAO_default_environment ()) = 0; - // The gateway must disconnect from all the relevant event channels, - // or any other communication media (such as multicast groups). + /// Obtain and modify the observer handle. void observer_handle (RtecEventChannelAdmin::Observer_Handle h); RtecEventChannelAdmin::Observer_Handle observer_handle (void) const; - // Obtain and modify the observer handle. private: RtecEventChannelAdmin::Observer_Handle handle_; }; // **************************************************************** +/** + * @class TAO_EC_Gateway_IIOP + * + * @brief Event Channel Gateway using IIOP. + * + * This class mediates among two event channels, it connects as a + * consumer of events with a remote event channel, and as a supplier + * of events with the local EC. + * As a consumer it gives a QoS designed to only accept the events + * in which *local* consumers are interested. + * Eventually the local EC should create this object and compute its + * QoS in an automated manner; but this requires some way to filter + * out the peers registered as consumers, otherwise we will get + * loops in the QoS graph. + * It uses exactly the same set of events in the publications list + * when connected as a supplier. + * + * @note + * An alternative implementation would be to register with the + * remote EC as a supplier, and then filter on the remote EC, but + * one of the objectives is to minimize network traffic. + * On the other hand the events will be pushed to remote consumers, + * event though they will be dropped upon receipt (due to the TTL + * field); IMHO this is another suggestion that the EC needs to know + * (somehow) which consumers are truly its peers in disguise. + * + * @todo: The class makes an extra copy of the events, we need to + * investigate if closer collaboration with its collocated EC could + * be used to remove that copy. + */ class TAO_RTEvent_Export TAO_EC_Gateway_IIOP : public TAO_EC_Gateway -// -// = TITLE -// Event Channel Gateway using IIOP. -// -// = DESCRIPTION -// This class mediates among two event channels, it connects as a -// consumer of events with a remote event channel, and as a supplier -// of events with the local EC. -// As a consumer it gives a QoS designed to only accept the events -// in which *local* consumers are interested. -// Eventually the local EC should create this object and compute its -// QoS in an automated manner; but this requires some way to filter -// out the peers registered as consumers, otherwise we will get -// loops in the QoS graph. -// It uses exactly the same set of events in the publications list -// when connected as a supplier. -// -// = NOTES -// An alternative implementation would be to register with the -// remote EC as a supplier, and then filter on the remote EC, but -// one of the objectives is to minimize network traffic. -// On the other hand the events will be pushed to remote consumers, -// event though they will be dropped upon receipt (due to the TTL -// field); IMHO this is another suggestion that the EC needs to know -// (somehow) which consumers are truly its peers in disguise. -// -// { public: TAO_EC_Gateway_IIOP (void); ~TAO_EC_Gateway_IIOP (void); + /// To do its job this class requires to know the local and remote + /// ECs it will connect to, void init (RtecEventChannelAdmin::EventChannel_ptr rmt_ec, RtecEventChannelAdmin::EventChannel_ptr lcl_ec, CORBA::Environment &ACE_TRY_ENV); - // To do its job this class requires to know the local and remote - // ECs it will connect to, + /// The channel is disconnecting. void disconnect_push_supplier (CORBA::Environment & = TAO_default_environment ()); - // The channel is disconnecting. + /// The channel is disconnecting. void disconnect_push_consumer (CORBA::Environment & = TAO_default_environment ()); - // The channel is disconnecting. + /// This is the Consumer side behavior, it pushes the events to the + /// local event channel. void push (const RtecEventComm::EventSet &events, CORBA::Environment & = TAO_default_environment ()); - // This is the Consumer side behavior, it pushes the events to the - // local event channel. + /// Disconnect and shutdown the gateway int shutdown (CORBA::Environment & = TAO_default_environment ()); - // Disconnect and shutdown the gateway // The following methods are documented in the base class. virtual void close (CORBA::Environment &env = TAO_default_environment ()); @@ -146,54 +132,56 @@ private: CORBA::Environment& env); protected: + /// Do the real work in init() void init_i (RtecEventChannelAdmin::EventChannel_ptr rmt_ec, RtecEventChannelAdmin::EventChannel_ptr lcl_ec, CORBA::Environment &ACE_TRY_ENV); - // Do the real work in init() protected: + /// Lock to synchronize internal changes ACE_SYNCH_MUTEX lock_; - // Lock to synchronize internal changes + /// How many threads are running push() we cannot make changes until + /// that reaches 0 CORBA::ULong busy_count_; - // How many threads are running push() we cannot make changes until - // that reaches 0 + /** + * An update_consumer() message arrived *while* we were doing a + * push() the modification is stored <pub_>, if multiple + * update_consumer messages arrive only the last one is executed. + */ int update_posted_; RtecEventChannelAdmin::ConsumerQOS c_qos_; - // An update_consumer() message arrived *while* we were doing a - // push() the modification is stored <pub_>, if multiple - // update_consumer messages arrive only the last one is executed. + /// The remote and the local EC, so we can reconnect when the list changes. RtecEventChannelAdmin::EventChannel_var rmt_ec_; RtecEventChannelAdmin::EventChannel_var lcl_ec_; - // The remote and the local EC, so we can reconnect when the list changes. + /// Our local and remote RT_Infos. RtecBase::handle_t rmt_info_; RtecBase::handle_t lcl_info_; - // Our local and remote RT_Infos. + /// Our consumer personality.... + /// If it is not 0 then we must deactivate the supplier ACE_PushConsumer_Adapter<TAO_EC_Gateway_IIOP> consumer_; - // Our consumer personality.... int consumer_is_active_; - // If it is not 0 then we must deactivate the supplier + /// Our supplier personality.... + /// If it is not 0 then we must deactivate the supplier ACE_PushSupplier_Adapter<TAO_EC_Gateway_IIOP> supplier_; - // Our supplier personality.... int supplier_is_active_; - // If it is not 0 then we must deactivate the supplier // We use a different Consumer_Proxy typedef ACE_Map_Manager<RtecEventComm::EventSourceID,RtecEventChannelAdmin::ProxyPushConsumer_ptr,ACE_Null_Mutex> Consumer_Map; typedef ACE_Map_Iterator<RtecEventComm::EventSourceID,RtecEventChannelAdmin::ProxyPushConsumer_ptr,ACE_Null_Mutex> Consumer_Map_Iterator; + /// We talk to the EC (as a supplier) using either an per-supplier + /// proxy or a generic proxy for the type only subscriptions. Consumer_Map consumer_proxy_map_; RtecEventChannelAdmin::ProxyPushConsumer_var default_consumer_proxy_; - // We talk to the EC (as a supplier) using either an per-supplier - // proxy or a generic proxy for the type only subscriptions. + /// We talk to the EC (as a consumer) using this proxy. RtecEventChannelAdmin::ProxyPushSupplier_var supplier_proxy_; - // We talk to the EC (as a consumer) using this proxy. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_Sched.h b/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_Sched.h index 5667fa0ac83..61c300147fa 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_Sched.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_Sched.h @@ -1,21 +1,18 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Gateway_Sched -// -// = AUTHOR -// Carlos O'Ryan -// -// = DESCRIPTION -// Extend the EC_Gateway_IIOP class to support the scheduling service. -// -// ============================================================================ +/** + * @file EC_Gateway_Sched.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + * + * + */ #ifndef TAO_EC_GATEWAY_SCHED_H #define TAO_EC_GATEWAY_SCHED_H @@ -27,16 +24,24 @@ // **************************************************************** +/** + * @class TAO_EC_Gateway_Sched + * + * @brief Extend the EC_Gateway_IIOP interface to support scheduling. + */ class TAO_RTSchedEvent_Export TAO_EC_Gateway_Sched : public TAO_EC_Gateway_IIOP -// -// = TITLE -// Extend the EC_Gateway_IIOP interface to support scheduling. -// { public: TAO_EC_Gateway_Sched (void); ~TAO_EC_Gateway_Sched (void); + /** + * To do its job this class requires to know the local and remote + * ECs it will connect to; furthermore it also requires to build + * RT_Infos for the local and remote schedulers. + * @todo part of the RT_Info is hardcoded, we need to make it + * parametric. + */ void init (RtecEventChannelAdmin::EventChannel_ptr rmt_ec, RtecEventChannelAdmin::EventChannel_ptr lcl_ec, RtecScheduler::Scheduler_ptr rmt_sched, @@ -44,11 +49,6 @@ public: const char* lcl_name, const char* rmt_name, CORBA::Environment &env = TAO_default_environment ()); - // To do its job this class requires to know the local and remote - // ECs it will connect to; furthermore it also requires to build - // RT_Infos for the local and remote schedulers. - // @@ TODO part of the RT_Info is hardcoded, we need to make it - // parametric. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_UDP.h b/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_UDP.h index 83ad6bfdf7e..2bd5c358116 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_UDP.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Gateway_UDP.h @@ -1,54 +1,52 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// TAO services -// -// = FILENAME -// EC_Gateway_UDP -// -// = AUTHOR -// Carlos O'Ryan -// -// = DESCRIPTION -// Define helper classes to propagate events between ECs using -// either UDP or multicast. -// The architecture is a bit complicated and deserves some -// explanation: sending the events over UDP (or mcast) is easy, a -// Consumer (TAO_ECG_UDP_Sender) subscribes for a certain set of -// events, its push() method marshalls the event set into a CDR -// stream that is sent using an ACE_SOCK_CODgram. The subscription -// set and IP address can be configured. -// Another helper class (TAO_ECG_UDP_Receiver) acts as a supplier of -// events; it receives a callback when an event is available on an -// ACE_SOCK_Dgram, it demarshalls the event and pushes it to the -// EC. Two ACE_Event_Handler classes are provided that can forward -// the events to this Supplier: TAO_ECG_Mcast_EH can receive events -// from a multicast group; TAO_ECG_UDP_EH can receive events from a -// regular UDP socket. -// -// Matching of the events types carried by a multicast group (or IP -// address) is up to the application. Gateway classes can be -// implemented to automate this: the EC informs its gateways about -// local changes in the subscriptions (for example), the Gateway -// could then consult an administrative server that will inform it -// which multicast groups carry those event types, it can then -// create the proper event handlers and TAO_ECG_Receivers. An -// analogous class can be implemented for the Supplier side. -// -// An alternative approach would be to look the current set of -// multicast groups and the events carried on each, using that -// information a suitable TAO_ECG_UDP_Receiver can be configured -// (and of course the Senders on the client side). -// -// = TODO -// The class makes an extra copy of the events, we need to -// investigate if closer collaboration with its collocated EC could -// be used to remove that copy. -// -// ============================================================================ +/** + * @file EC_Gateway_UDP.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + * + * Define helper classes to propagate events between ECs using + * either UDP or multicast. + * The architecture is a bit complicated and deserves some + * explanation: sending the events over UDP (or mcast) is easy, a + * Consumer (TAO_ECG_UDP_Sender) subscribes for a certain set of + * events, its push() method marshalls the event set into a CDR + * stream that is sent using an ACE_SOCK_CODgram. The subscription + * set and IP address can be configured. + * Another helper class (TAO_ECG_UDP_Receiver) acts as a supplier of + * events; it receives a callback when an event is available on an + * ACE_SOCK_Dgram, it demarshalls the event and pushes it to the + * EC. Two ACE_Event_Handler classes are provided that can forward + * the events to this Supplier: TAO_ECG_Mcast_EH can receive events + * from a multicast group; TAO_ECG_UDP_EH can receive events from a + * regular UDP socket. + * + * Matching of the events types carried by a multicast group (or IP + * address) is up to the application. Gateway classes can be + * implemented to automate this: the EC informs its gateways about + * local changes in the subscriptions (for example), the Gateway + * could then consult an administrative server that will inform it + * which multicast groups carry those event types, it can then + * create the proper event handlers and TAO_ECG_Receivers. An + * analogous class can be implemented for the Supplier side. + * + * An alternative approach would be to look the current set of + * multicast groups and the events carried on each, using that + * information a suitable TAO_ECG_UDP_Receiver can be configured + * (and of course the Senders on the client side). + * + * @todo The class makes an extra copy of the events, we need to + * investigate if closer collaboration with its collocated EC could + * be used to remove that copy. + * + * + */ #ifndef TAO_EC_GATEWAY_UDP_H #define TAO_EC_GATEWAY_UDP_H @@ -67,57 +65,49 @@ class TAO_ECG_UDP_Out_Endpoint; +/** + * @class TAO_ECG_UDP_Sender + * + * @brief Send events received from a "local" EC using UDP. + * + * This class connect as a consumer to an EventChannel + * and it sends the events using UDP, the UDP address can be a + * normal IP address or it can be a multicast group. + * The UDP address is obtained from a RtecUDPAdmin::AddrServer + * class. + * It marshalls the events using TAO CDR classes. + * + * <H2>MESSAGE FORMAT</H2> + * The messages header are encapsulated using CDR, with the + * following format: + * struct Header { + * octet byte_order_flags; + * // bit 0 represents the byte order as in GIOP 1.1 + * // bit 1 is set if this is the last fragment + * unsigned long request_id; + * // The request ID, senders must not send two requests with + * // the same ID, senders can be distinguished using recvfrom.. + * unsigned long request_size; + * // The size of this request, this can be used to pre-allocate + * // the request buffer. + * unsgined long fragment_size; + * // The size of this fragment, excluding the header... + * unsigned long fragment_offset; + * // Where does this fragment fit in the complete message... + * unsigned long fragment_id; + * // The ID of this fragment... + * unsigned long fragment_count; + * // The total number of fragments to expect in this request + * + * // @todo This could be eliminated if efficient reassembly + * // could be implemented without it. + * octet padding[4]; + * + * // Ensures the header ends at an 8-byte boundary. + * }; // size (in CDR stream) = 32 + */ class TAO_RTEvent_Export TAO_ECG_UDP_Sender : public POA_RtecEventComm::PushConsumer { - // - // = TITLE - // Send events received from a "local" EC using UDP. - // - // = DESCRIPTION - // This class connect as a consumer to an EventChannel - // and it sends the events using UDP, the UDP address can be a - // normal IP address or it can be a multicast group. - // The UDP address is obtained from a RtecUDPAdmin::AddrServer - // class. - // It marshalls the events using TAO CDR classes. - // - // = MESSAGE FORMAT - // - // The messages header are encapsulated using CDR, with the - // following format: - // - // struct Header { - // octet byte_order_flags; - // // bit 0 represents the byte order as in GIOP 1.1 - // // bit 1 is set if this is the last fragment - // - // unsigned long request_id; - // // The request ID, senders must not send two requests with - // // the same ID, senders can be distinguished using recvfrom.. - // - // unsigned long request_size; - // // The size of this request, this can be used to pre-allocate - // // the request buffer. - // - // unsgined long fragment_size; - // // The size of this fragment, excluding the header... - // - // unsigned long fragment_offset; - // // Where does this fragment fit in the complete message... - // - // unsigned long fragment_id; - // // The ID of this fragment... - // - // unsigned long fragment_count; - // // The total number of fragments to expect in this request - // // @@ TODO This could be eliminated if efficient reassembly - // // could be implemented without it. - // - // octet padding[4]; - // // Ensures the header ends at an 8-byte boundary. - // }; // size (in CDR stream) = 32 - // - // public: TAO_ECG_UDP_Sender (void); @@ -128,51 +118,60 @@ public: ECG_DEFAULT_MTU = 1024 }; + /// Get the local endpoint used to send the events. int get_local_addr (ACE_INET_Addr& addr); - // Get the local endpoint used to send the events. + /** + * To do its job this class requires to know the local EC it will + * connect to; it also requires to build an RT_Info for the local + * scheduler. + * It only keeps a copy of its SupplierProxy, used for later + * connection and disconnections. + * @todo part of the RT_Info is hardcoded, we need to make it + * parametric. + */ void init (RtecEventChannelAdmin::EventChannel_ptr lcl_ec, RtecUDPAdmin::AddrServer_ptr addr_server, TAO_ECG_UDP_Out_Endpoint *endpoint, CORBA::Environment &env = TAO_default_environment ()); - // To do its job this class requires to know the local EC it will - // connect to; it also requires to build an RT_Info for the local - // scheduler. - // It only keeps a copy of its SupplierProxy, used for later - // connection and disconnections. - // @@ TODO part of the RT_Info is hardcoded, we need to make it - // parametric. + /** + * The sender may need to fragment the message, otherwise the + * network may drop the packets. + * Setting the MTU can fail if the value is too small (at least the + * header + 8 bytes must fit). + */ int mtu (CORBA::ULong mtu); CORBA::ULong mtu (void) const; - // The sender may need to fragment the message, otherwise the - // network may drop the packets. - // Setting the MTU can fail if the value is too small (at least the - // header + 8 bytes must fit). + /// Disconnect and shutdown the sender, no further connections will + /// work unless init() is called again. void shutdown (CORBA::Environment & = TAO_default_environment ()); - // Disconnect and shutdown the sender, no further connections will - // work unless init() is called again. + /// Connect (or reconnect) to the EC with the given subscriptions. void open (RtecEventChannelAdmin::ConsumerQOS &sub, CORBA::Environment &env = TAO_default_environment ()); - // Connect (or reconnect) to the EC with the given subscriptions. + /// Disconnect from the EC, but reconnection is still possible. void close (CORBA::Environment &env = TAO_default_environment ()); - // Disconnect from the EC, but reconnection is still possible. + /// The PushConsumer methods. virtual void disconnect_push_consumer (CORBA::Environment & = TAO_default_environment ()) ACE_THROW_SPEC ((CORBA::SystemException)); virtual void push (const RtecEventComm::EventSet &events, CORBA::Environment & = TAO_default_environment ()) ACE_THROW_SPEC ((CORBA::SystemException)); - // The PushConsumer methods. private: + /// Return the datagram... ACE_SOCK_Dgram& dgram (void); - // Return the datagram... + /** + * Send one fragment, the first entry in the iovec is used to send + * the header, the rest of the iovec array should contain pointers + * to the actual data. + */ void send_fragment (const RtecUDPAdmin::UDP_Addr& udp_addr, CORBA::ULong request_id, CORBA::ULong request_size, @@ -183,114 +182,115 @@ private: iovec iov[], int iovcnt, CORBA::Environment &env = TAO_default_environment ()); - // Send one fragment, the first entry in the iovec is used to send - // the header, the rest of the iovec array should contain pointers - // to the actual data. + /** + * Count the number of fragments that will be required to send the + * message blocks in the range [begin,end) + * The maximum fragment payload (i.e. the size without the header is + * also required); <total_length> returns the total message size. + */ CORBA::ULong compute_fragment_count (const ACE_Message_Block* begin, const ACE_Message_Block* end, int iov_size, CORBA::ULong max_fragment_payload, CORBA::ULong& total_length); - // Count the number of fragments that will be required to send the - // message blocks in the range [begin,end) - // The maximum fragment payload (i.e. the size without the header is - // also required); <total_length> returns the total message size. private: + /// The remote and the local EC, so we can reconnect when the + /// subscription list changes. RtecEventChannelAdmin::EventChannel_var lcl_ec_; - // The remote and the local EC, so we can reconnect when the - // subscription list changes. + /// We talk to the EC (as a consumer) using this proxy. RtecEventChannelAdmin::ProxyPushSupplier_var supplier_proxy_; - // We talk to the EC (as a consumer) using this proxy. + /// We query this object to determine where are the events sent. RtecUDPAdmin::AddrServer_var addr_server_; - // We query this object to determine where are the events sent. + /// The datagram used to sendto(), this object is *not* owned by the + /// UDP_Sender. TAO_ECG_UDP_Out_Endpoint *endpoint_; - // The datagram used to sendto(), this object is *not* owned by the - // UDP_Sender. + /// The MTU for this sender... CORBA::ULong mtu_; - // The MTU for this sender... }; // **************************************************************** +/** + * @class TAO_ECG_UDP_Out_Endpoint + * + * @brief Maintains information about an outgoing endpoint. + * + * UDP senders can share a single endpoint to send UDP packets, + * but there is more state associated with this endpoint than its + * datagram SAP; for instance we need to keep track of the request + * id. + */ class TAO_RTEvent_Export TAO_ECG_UDP_Out_Endpoint { - // - // = TITLE - // Maintains information about an outgoing endpoint. - // - // = DESCRIPTION - // UDP senders can share a single endpoint to send UDP packets, - // but there is more state associated with this endpoint than its - // datagram SAP; for instance we need to keep track of the request - // id. public: + /// Constructor TAO_ECG_UDP_Out_Endpoint (void); - // Constructor + /// Constructor ~TAO_ECG_UDP_Out_Endpoint (void); - // Constructor + /// Obtain the datagram associated with this endpoint. Clients of + /// this class must open, and register (if necessary) this datagram. ACE_SOCK_Dgram& dgram (void); - // Obtain the datagram associated with this endpoint. Clients of - // this class must open, and register (if necessary) this datagram. + /// Obtain the next request id. CORBA::ULong next_request_id (void); - // Obtain the next request id. + /// The endpoint can detect if a data-gram was sent by itself, this + /// is useful to ignore or remove messages sent by the same process. CORBA::Boolean is_loopback (const ACE_INET_Addr& from); - // The endpoint can detect if a data-gram was sent by itself, this - // is useful to ignore or remove messages sent by the same process. private: + /// The request id.... ACE_Atomic_Op<ACE_SYNCH_MUTEX,CORBA::ULong> request_id_generator_; - // The request id.... + /// The datagram.... ACE_SOCK_Dgram dgram_; - // The datagram.... + /// cache the port-number so we can quickly determine if an event is + /// coming from another endpoint. u_short port_number_; - // cache the port-number so we can quickly determine if an event is - // coming from another endpoint. + /// Keep the list of local interfaces, needed for the is_loopback + /// method. size_t if_count_; ACE_INET_Addr* ifs_; - // Keep the list of local interfaces, needed for the is_loopback - // method. }; // **************************************************************** +/** + * @class TAO_ECG_UDP_Request_Index + * + * @brief Index to the request map. + * + * This object is used to index the map of incomplete (due to + * fragmentation) requests. + */ class TAO_RTEvent_Export TAO_ECG_UDP_Request_Index { - // = TITLE - // Index to the request map. - // - // = DESCRIPTION - // This object is used to index the map of incomplete (due to - // fragmentation) requests. - // public: + /// default copy ctor, dtor and operator= TAO_ECG_UDP_Request_Index (void); TAO_ECG_UDP_Request_Index (const ACE_INET_Addr& from, CORBA::ULong request_id); - // default copy ctor, dtor and operator= // The ACE_INLINE macros here are to keep g++ 2.7.X happy, // otherwise it thinks they are used as inline functions before // beign used as such.... Apparently in the template code for the // Hash_Map_Manager. + /// Return a hash value... ACE_INLINE u_long hash (void) const; - // Return a hash value... + /// Compare ACE_INLINE int operator== (const TAO_ECG_UDP_Request_Index& rhs) const; ACE_INLINE int operator!= (const TAO_ECG_UDP_Request_Index& rhs) const; - // Compare ACE_INET_Addr from; CORBA::ULong request_id; @@ -298,15 +298,16 @@ public: // **************************************************************** +/** + * @class TAO_ECG_UDP_Request_Entry + * + * @brief Keeps information about an incomplete request. + * + * When a request arrives in fragments this object is used to + * keep track of the incoming data. + */ class TAO_RTEvent_Export TAO_ECG_UDP_Request_Entry { - // = TITLE - // Keeps information about an incomplete request. - // - // = DESCRIPTION - // When a request arrives in fragments this object is used to - // keep track of the incoming data. - // public: enum { ECG_DEFAULT_FRAGMENT_BUFSIZ = 8 @@ -317,75 +318,75 @@ public: // TAO_ECG_UDP_Request_Entry& operator=(const TAO_ECG_UDP_Request_Entry& rhs); ~TAO_ECG_UDP_Request_Entry (void); + /// Initialize the fragment, allocating memory, etc. TAO_ECG_UDP_Request_Entry (CORBA::Boolean byte_order, CORBA::ULong request_id, CORBA::ULong request_size, CORBA::ULong fragment_count); - // Initialize the fragment, allocating memory, etc. + /// Validate a fragment, it should be rejected if it is invalid.. int validate_fragment (CORBA::Boolean byte_order, CORBA::ULong request_size, CORBA::ULong fragment_size, CORBA::ULong fragment_offset, CORBA::ULong fragment_id, CORBA::ULong fragment_count) const; - // Validate a fragment, it should be rejected if it is invalid.. + /// Has <fragment_id> been received? int test_received (CORBA::ULong fragment_id) const; - // Has <fragment_id> been received? + /// Mark <fragment_id> as received, reset timeout counter... void mark_received (CORBA::ULong fragment_id); - // Mark <fragment_id> as received, reset timeout counter... + /// Is the message complete? int complete (void) const; - // Is the message complete? + /// Return a buffer for the fragment at offset <fragment_offset> char* fragment_buffer (CORBA::ULong fragment_offset); - // Return a buffer for the fragment at offset <fragment_offset> + /// Decode the events, the message must be complete. void decode (RtecEventComm::EventSet& event, CORBA::Environment &env = TAO_default_environment ()); - // Decode the events, the message must be complete. + /// Increment the timeout counter... void inc_timeout (void); - // Increment the timeout counter... + /// Get the timeout counter.... int get_timeout (void) const; - // Get the timeout counter.... private: + /// This attributes should remain constant in all the fragments, used + /// for validation.... CORBA::Boolean byte_order_; CORBA::ULong request_id_; CORBA::ULong request_size_; CORBA::ULong fragment_count_; - // This attributes should remain constant in all the fragments, used - // for validation.... CORBA::ULong timeout_counter_; ACE_Message_Block payload_; + /// This is a bit vector, used to keep track of the received buffers. CORBA::ULong* received_fragments_; int own_received_fragments_; CORBA::ULong received_fragments_size_; CORBA::ULong default_received_fragments_[ECG_DEFAULT_FRAGMENT_BUFSIZ]; - // This is a bit vector, used to keep track of the received buffers. }; // **************************************************************** class TAO_ECG_UDP_Receiver; +/** + * @class TAO_ECG_UDP_TH + * + * @brief Timer Handler for the UDP Receivers. + * + * This object receives timer events from the reactor and forwards + * them to the UDP_Receiver; which uses those events to expire old + * messages that did not receive all their fragments. + */ class TAO_RTEvent_Export TAO_ECG_UDP_TH : public ACE_Event_Handler { - // - // = TITLE - // Timer Handler for the UDP Receivers. - // - // = DESCRIPTION - // This object receives timer events from the reactor and forwards - // them to the UDP_Receiver; which uses those events to expire old - // messages that did not receive all their fragments. - // public: TAO_ECG_UDP_TH (TAO_ECG_UDP_Receiver *recv); @@ -394,41 +395,49 @@ public: const void* act); private: + /// We callback to this object when a message arrives. TAO_ECG_UDP_Receiver* receiver_; - // We callback to this object when a message arrives. }; // **************************************************************** +/** + * @class TAO_ECG_UDP_Receiver + * + * @brief Decodes events from an ACE_SOCK_Dgram and pushes them to the + * Event_Channel. + * + * This supplier receives events from an ACE_SOCK_Dgram, either + * from a UDP socket or a Mcast group, decodes them and push them + * to the EC. + * = REASSEMBLY + * Whenever an incomplete fragment is received (one with + * fragment_count > 1) we allocate an entry for the message in an + * map indexed by (host,port,request_id). The entry contains the + * buffer, a bit vector to keep track of the fragments received + * so far, and a timeout counter. This timeout counter is set to + * 0 on each (new) fragment arrival, and incremented on a regular + * basis. If the counter reaches a maximum value the message is + * dropped. + * Once all the fragments have been received the message is sent + * up, and the memory reclaimed. The entry is *not* removed until + * the timer expires (to handle re-transmitions). + */ class TAO_RTEvent_Export TAO_ECG_UDP_Receiver : public POA_RtecEventComm::PushSupplier { - // - // = TITLE - // Decodes events from an ACE_SOCK_Dgram and pushes them to the - // Event_Channel. - // - // = DESCRIPTION - // This supplier receives events from an ACE_SOCK_Dgram, either - // from a UDP socket or a Mcast group, decodes them and push them - // to the EC. - // - // = REASSEMBLY - // - // Whenever an incomplete fragment is received (one with - // fragment_count > 1) we allocate an entry for the message in an - // map indexed by (host,port,request_id). The entry contains the - // buffer, a bit vector to keep track of the fragments received - // so far, and a timeout counter. This timeout counter is set to - // 0 on each (new) fragment arrival, and incremented on a regular - // basis. If the counter reaches a maximum value the message is - // dropped. - // Once all the fragments have been received the message is sent - // up, and the memory reclaimed. The entry is *not* removed until - // the timer expires (to handle re-transmitions). - // public: TAO_ECG_UDP_Receiver (void); + /** + * To do its job this class requires to know the local EC it will + * connect to; it also requires to build an RT_Info for the local + * scheduler. + * The <reactor> is used to receive timeout events.. + * The <ignore_from> endpoint is used to remove events generated by + * the same process. + * @todo part of the RT_Info is hardcoded, we need to make it + * parametric. + */ void init (RtecEventChannelAdmin::EventChannel_ptr lcl_ec, TAO_ECG_UDP_Out_Endpoint* ignore_from, RtecUDPAdmin::AddrServer_ptr addr_server, @@ -436,57 +445,51 @@ public: const ACE_Time_Value &expire_interval, int max_timeout, CORBA::Environment &env = TAO_default_environment ()); - // To do its job this class requires to know the local EC it will - // connect to; it also requires to build an RT_Info for the local - // scheduler. - // The <reactor> is used to receive timeout events.. - // The <ignore_from> endpoint is used to remove events generated by - // the same process. - // @@ TODO part of the RT_Info is hardcoded, we need to make it - // parametric. + /// Disconnect and shutdown the gateway, no further connectsions void shutdown (CORBA::Environment & = TAO_default_environment ()); - // Disconnect and shutdown the gateway, no further connectsions + /// Connect to the EC using the given publications lists. void open (RtecEventChannelAdmin::SupplierQOS& pub, CORBA::Environment &env = TAO_default_environment ()); - // Connect to the EC using the given publications lists. + /// Disconnect to the EC. virtual void close (CORBA::Environment &env = TAO_default_environment ()); - // Disconnect to the EC. + /** + * The Event_Handlers call this method when data is available at the + * socket, the <dgram> must be ready for reading and contain a full + * event. + */ int handle_input (ACE_SOCK_Dgram& dgram); - // The Event_Handlers call this method when data is available at the - // socket, the <dgram> must be ready for reading and contain a full - // event. + /// The timer has expired, must update all the unreceived + /// messages... int handle_timeout (const ACE_Time_Value& tv, const void* act); - // The timer has expired, must update all the unreceived - // messages... // The PushSupplier method. virtual void disconnect_push_supplier (CORBA::Environment & = TAO_default_environment ()) ACE_THROW_SPEC ((CORBA::SystemException)); + /// Call the RtecUDPAdmin::AddrServer void get_addr (const RtecEventComm::EventHeader& header, RtecUDPAdmin::UDP_Addr_out addr, CORBA::Environment &env = TAO_default_environment ()); - // Call the RtecUDPAdmin::AddrServer private: + /// The remote and the local EC, so we can reconnect when the list changes. RtecEventChannelAdmin::EventChannel_var lcl_ec_; - // The remote and the local EC, so we can reconnect when the list changes. + /// We talk to the EC (as a consumer) using this proxy. RtecEventChannelAdmin::ProxyPushConsumer_var consumer_proxy_; - // We talk to the EC (as a consumer) using this proxy. + /// Ignore any events coming from this IP addres. TAO_ECG_UDP_Out_Endpoint* ignore_from_; - // Ignore any events coming from this IP addres. + /// The server used to map event types into multicast groups. RtecUDPAdmin::AddrServer_var addr_server_; - // The server used to map event types into multicast groups. typedef ACE_Hash_Map_Manager<TAO_ECG_UDP_Request_Index, TAO_ECG_UDP_Request_Entry*, @@ -494,128 +497,140 @@ private: typedef ACE_Hash_Map_Entry<TAO_ECG_UDP_Request_Index, TAO_ECG_UDP_Request_Entry*> Request_Map_Entry; + /// The map containing all the incoming requests which have been + /// partially received. Request_Map request_map_; - // The map containing all the incoming requests which have been - // partially received. + /// To receive the timeouts.. TAO_ECG_UDP_TH timeout_handler_; - // To receive the timeouts.. + /// The reactor we are using for the timeout handler... ACE_Reactor* reactor_; - // The reactor we are using for the timeout handler... + /// How many timeouts before we expire a message... int max_timeout_; - // How many timeouts before we expire a message... }; // **************************************************************** +/** + * @class TAO_ECG_UDP_EH + * + * @brief Event Handler for UDP messages. + * + * This object receives callbacks from the Reactor when data is + * available on a UDP socket, it forwards to the ECG_UDP_Receiver + * which reads the events and transform it into an event. + */ class TAO_RTEvent_Export TAO_ECG_UDP_EH : public ACE_Event_Handler { - // - // = TITLE - // Event Handler for UDP messages. - // - // = DESCRIPTION - // This object receives callbacks from the Reactor when data is - // available on a UDP socket, it forwards to the ECG_UDP_Receiver - // which reads the events and transform it into an event. - // public: TAO_ECG_UDP_EH (TAO_ECG_UDP_Receiver *recv); + /// Open the datagram and register with this->reactor() int open (const ACE_INET_Addr& ipaddr, int reuse_addr = 0); - // Open the datagram and register with this->reactor() + /// Close the datagram and unregister with the reactor. int close (void); - // Close the datagram and unregister with the reactor. + /** + * Obtain the dgram, this is one of those "controlled violations of + * type safety", allowing the user to setup options and gain access + * to low-level features. + */ ACE_SOCK_Dgram &dgram (void); - // Obtain the dgram, this is one of those "controlled violations of - // type safety", allowing the user to setup options and gain access - // to low-level features. // Reactor callbacks virtual int handle_input (ACE_HANDLE fd); virtual ACE_HANDLE get_handle (void) const; private: + /// The datagram used to receive the data. ACE_SOCK_Dgram dgram_; - // The datagram used to receive the data. + /// We callback to this object when a message arrives. TAO_ECG_UDP_Receiver* receiver_; - // We callback to this object when a message arrives. }; // **************************************************************** +/** + * @class TAO_ECG_Mcast_EH + * + * @brief Event Handler for UDP messages. + * + * This object receives callbacks from the Reactor when data is + * available on the mcast socket, it forwards to the UDP_Receive + * gateway which reads the events and transform it into an event. + */ class TAO_RTEvent_Export TAO_ECG_Mcast_EH : public ACE_Event_Handler { - // - // = TITLE - // Event Handler for UDP messages. - // - // = DESCRIPTION - // This object receives callbacks from the Reactor when data is - // available on the mcast socket, it forwards to the UDP_Receive - // gateway which reads the events and transform it into an event. - // public: + /** + * Constructor, the messages received by this EH are forwarded to + * the <recv>. + * It is possible to select the NIC where the multicast messages are + * expected using <net_if> + */ TAO_ECG_Mcast_EH (TAO_ECG_UDP_Receiver *recv, const ACE_TCHAR *net_if = 0); - // Constructor, the messages received by this EH are forwarded to - // the <recv>. - // It is possible to select the NIC where the multicast messages are - // expected using <net_if> + /// Destructor virtual ~TAO_ECG_Mcast_EH (void); - // Destructor + /** + * Register for changes in the EC subscription list. + * When the subscription list becomes non-empty we join the proper + * multicast groups (using the receiver to translate between event + * types and mcast groups) and the class registers itself with the + * reactor. + */ int open (RtecEventChannelAdmin::EventChannel_ptr ec, CORBA::Environment &env = TAO_default_environment ()); - // Register for changes in the EC subscription list. - // When the subscription list becomes non-empty we join the proper - // multicast groups (using the receiver to translate between event - // types and mcast groups) and the class registers itself with the - // reactor. + /** + * Remove ourselves from the event channel, unsubscribe from the + * multicast groups, close the sockets and unsubscribe from the + * reactor. + */ int close (CORBA::Environment &env = TAO_default_environment ()); - // Remove ourselves from the event channel, unsubscribe from the - // multicast groups, close the sockets and unsubscribe from the - // reactor. + /** + * Obtain the dgram, this is one of those "controlled violations of + * type safety", allowing the user to setup options and gain access + * to low-level features. + */ ACE_SOCK_Dgram &dgram (void); - // Obtain the dgram, this is one of those "controlled violations of - // type safety", allowing the user to setup options and gain access - // to low-level features. + /// Reactor callbacks virtual int handle_input (ACE_HANDLE fd); virtual ACE_HANDLE get_handle (void) const; - // Reactor callbacks + /// The Observer methods void update_consumer (const RtecEventChannelAdmin::ConsumerQOS& sub, CORBA::Environment &env = TAO_default_environment ()) ACE_THROW_SPEC ((CORBA::SystemException)); void update_supplier (const RtecEventChannelAdmin::SupplierQOS& pub, CORBA::Environment &env = TAO_default_environment ()) ACE_THROW_SPEC ((CORBA::SystemException)); - // The Observer methods + /** + * @class Observer + * + * @brief Observe changes in the EC subscriptions. + * + * As the subscriptions on the EC change we also change the + * mcast groups that we join. + * We could use the TIE classes, but they don't work in all + * compilers. + */ class Observer : public POA_RtecEventChannelAdmin::Observer { - // = TITLE - // Observe changes in the EC subscriptions. - // - // = DESCRIPTION - // As the subscriptions on the EC change we also change the - // mcast groups that we join. - // We could use the TIE classes, but they don't work in all - // compilers. public: + /// We report changes in the EC subscriptions to the event + /// handler. Observer (TAO_ECG_Mcast_EH* eh); - // We report changes in the EC subscriptions to the event - // handler. // The Observer methods virtual void update_consumer ( @@ -630,34 +645,34 @@ public: ACE_THROW_SPEC ((CORBA::SystemException)); private: + /// Our callback object. TAO_ECG_Mcast_EH *eh_; - // Our callback object. }; private: + /// Control the multicast group subscriptions int subscribe (const ACE_INET_Addr &mcast_addr); int unsubscribe (const ACE_INET_Addr &mcast_addr); - // Control the multicast group subscriptions private: + /// The NIC name used to subscribe for multicast traffic. ACE_TCHAR *net_if_; - // The NIC name used to subscribe for multicast traffic. + /// The datagram used to receive the data. ACE_SOCK_Dgram_Mcast dgram_; - // The datagram used to receive the data. + /// We callback to this object when a message arrives. TAO_ECG_UDP_Receiver* receiver_; - // We callback to this object when a message arrives. + /// This object will call us back when the subscription list + /// changes. Observer observer_; - // This object will call us back when the subscription list - // changes. + /// Keep the handle of the observer so we can unregister later. RtecEventChannelAdmin::Observer_Handle handle_; - // Keep the handle of the observer so we can unregister later. + /// The Event Channel. RtecEventChannelAdmin::EventChannel_var ec_; - // The Event Channel. }; #if defined(__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_MT_Dispatching.h b/TAO/orbsvcs/orbsvcs/Event/EC_MT_Dispatching.h index 17129ca6336..439c609bcf6 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_MT_Dispatching.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_MT_Dispatching.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_MT_Dispatching -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_MT_Dispatching.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_MT_DISPATCHING_H #define TAO_EC_MT_DISPATCHING_H @@ -36,23 +26,24 @@ class TAO_EC_Event_Channel; +/** + * @class TAO_EC_MT_Dispatching + * + * @brief Dispatching strategy that minimizes mt inversion. + * + * This strategy uses a single queue, serviced by one or more + * threads. It's main purpose is to decouple the suppliers from + * the client execution time, specially in the collocated case. + */ class TAO_RTEvent_Export TAO_EC_MT_Dispatching : public TAO_EC_Dispatching { - // = TITLE - // Dispatching strategy that minimizes mt inversion. - // - // = DESCRIPTION - // This strategy uses a single queue, serviced by one or more - // threads. It's main purpose is to decouple the suppliers from - // the client execution time, specially in the collocated case. - // public: + /// Constructor + /// It will create <nthreads> servicing threads... TAO_EC_MT_Dispatching (int nthreads, int thread_creation_flags, int thread_priority, int force_activate); - // Constructor - // It will create <nthreads> servicing threads... // = The EC_Dispatching methods. virtual void activate (void); @@ -69,31 +60,31 @@ public: CORBA::Environment& env); private: + /// Use our own thread manager. ACE_Thread_Manager thread_manager_; - // Use our own thread manager. + /// The number of active tasks int nthreads_; - // The number of active tasks + /// The flags (THR_BOUND, THR_NEW_LWP, etc.) used to create the + /// dispatching threads. int thread_creation_flags_; - // The flags (THR_BOUND, THR_NEW_LWP, etc.) used to create the - // dispatching threads. + /// The priority of the dispatching threads. int thread_priority_; - // The priority of the dispatching threads. + /// If activation at the requested priority fails then we fallback on + /// the defaults for thread activation. int force_activate_; - // If activation at the requested priority fails then we fallback on - // the defaults for thread activation. + /// The dispatching task TAO_EC_Dispatching_Task task_; - // The dispatching task + /// Synchronize access to internal data ACE_SYNCH_MUTEX lock_; - // Synchronize access to internal data + /// Are the threads running? int active_; - // Are the threads running? }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Masked_Type_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Masked_Type_Filter.h index 0e0c8e80ed1..4caa321b9f6 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Masked_Type_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Masked_Type_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Masked_Type_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Masked_Type_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_MASKED_TYPE_FILTER_H #define TAO_EC_MASKED_TYPE_FILTER_H @@ -32,33 +22,29 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Masked_Type_Filter + * + * @brief A masked type filter. + * + * This filter only accepts events whose type and/or source have + * a given value when a bitmask is applied to them. + * In short the filter checks that: + * (event.header.type & type_mask) == type_value + * and that: + * (event.header.source & source_mask) == source_value + */ class TAO_RTEvent_Export TAO_EC_Masked_Type_Filter : public TAO_EC_Filter { - // = TITLE - // A masked type filter. - // - // = DESCRIPTION - // This filter only accepts events whose type and/or source have - // a given value when a bitmask is applied to them. - // In short the filter checks that: - // - // (event.header.type & type_mask) == type_value - // - // and that: - // - // (event.header.source & source_mask) == source_value - // - // = MEMORY MANAGMENT - // public: + /// Constructor. TAO_EC_Masked_Type_Filter (CORBA::ULong source_mask, CORBA::ULong type_mask, CORBA::ULong source_value, CORBA::ULong type_value); - // Constructor. + /// Destructor virtual ~TAO_EC_Masked_Type_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -91,13 +77,13 @@ private: (const TAO_EC_Masked_Type_Filter&)) private: + /// The bitmasks CORBA::ULong source_mask_; CORBA::ULong type_mask_; - // The bitmasks + /// The values CORBA::ULong source_value_; CORBA::ULong type_value_; - // The values }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Negation_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Negation_Filter.h index 6d101050de5..219ea998789 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Negation_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Negation_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Negation_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Negation_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_NEGATION_FILTER_H #define TAO_EC_NEGATION_FILTER_H @@ -33,24 +23,25 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Negation_Filter + * + * @brief The negation filter. + * + * This filter accepts all the events rejected by its child, and + * rejects any events accepted by the child. + * + * <H2>Memory Management</H2> + * It assumes ownership of its child. + */ class TAO_RTEvent_Export TAO_EC_Negation_Filter : public TAO_EC_Filter { - // = TITLE - // The negation filter. - // - // = DESCRIPTION - // This filter accepts all the events rejected by its child, and - // rejects any events accepted by the child. - // - // = MEMORY MANAGMENT - // It assumes ownership of its child. - // public: + /// Constructor. It assumes ownership of the child. TAO_EC_Negation_Filter (TAO_EC_Filter* child); - // Constructor. It assumes ownership of the child. + /// Destructor virtual ~TAO_EC_Negation_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in @@ -84,8 +75,8 @@ private: (const TAO_EC_Negation_Filter&)) private: + /// The child TAO_EC_Filter* child_; - // The child }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Null_Factory.h b/TAO/orbsvcs/orbsvcs/Event/EC_Null_Factory.h index 78b0396a863..7484ebc8039 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Null_Factory.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Null_Factory.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Null_Factory -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Null_Factory.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_NULL_FACTORY_H #define TAO_EC_NULL_FACTORY_H @@ -32,26 +22,25 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Null_Factory + * + * @brief The factory for a simple event channel. + * + * The simplest configuration for an event channel does no + * filtering and uses reactive dispatching. This class is used to + * configure such an event channel. + * A fixed POA is used for servant activation. + * This object creates a single instance of the Supplier + */ class TAO_RTEvent_Export TAO_EC_Null_Factory : public TAO_EC_Factory { - // = TITLE - // The factory for a simple event channel. - // - // = DESCRIPTION - // The simplest configuration for an event channel does no - // filtering and uses reactive dispatching. This class is used to - // configure such an event channel. - // A fixed POA is used for servant activation. - // This object creates a single instance of the Supplier - // - // = MEMORY MANAGMENT - // public: + /// Constructor TAO_EC_Null_Factory (void); - // Constructor + /// destructor... virtual ~TAO_EC_Null_Factory (void); - // destructor... // = The EC_Factory methods virtual TAO_EC_Dispatching* diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Null_Scheduling.h b/TAO/orbsvcs/orbsvcs/Event/EC_Null_Scheduling.h index c11b579776b..bd1448395e7 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Null_Scheduling.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Null_Scheduling.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Null_Scheduling -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Null_Scheduling.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_NULL_SCHEDULING_H #define TAO_EC_NULL_SCHEDULING_H @@ -33,34 +23,33 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Null_Scheduling + * + * @brief A scheduling strategy that uses TAO's real-time scheduler + * + * This implementation of the Scheduling_Strategy uses TAO's + * real-time scheduler. + */ class TAO_RTEvent_Export TAO_EC_Null_Scheduling : public TAO_EC_Scheduling_Strategy { - // = TITLE - // A scheduling strategy that uses TAO's real-time scheduler - // - // = DESCRIPTION - // This implementation of the Scheduling_Strategy uses TAO's - // real-time scheduler. - // - // = MEMORY MANAGMENT - // public: + /// Constructor. TAO_EC_Null_Scheduling (void); - // Constructor. + /// Add all the dependencies between <supplier> and <consumer> virtual void add_proxy_supplier_dependencies ( TAO_EC_ProxyPushSupplier *supplier, TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &ACE_TRY_ENV); - // Add all the dependencies between <supplier> and <consumer> + /// Initializes <qos_info> based on the QoS information for + /// <consumer> and the event header. virtual void init_event_qos ( const RtecEventComm::EventHeader& header, TAO_EC_ProxyPushConsumer *consumer, TAO_EC_QOS_Info& qos_info, CORBA::Environment &ACE_TRY_ENV); - // Initializes <qos_info> based on the QoS information for - // <consumer> and the event header. private: ACE_UNIMPLEMENTED_FUNC (TAO_EC_Null_Scheduling diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_ObserverStrategy.h b/TAO/orbsvcs/orbsvcs/Event/EC_ObserverStrategy.h index 682c4f724d6..fed699df0aa 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_ObserverStrategy.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_ObserverStrategy.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_ObserverStrategy -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_ObserverStrategy.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_OBSERVERSTRATEGY_H #define TAO_EC_OBSERVERSTRATEGY_H @@ -42,26 +32,27 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushConsumer; class TAO_EC_ProxyPushSupplier; +/** + * @class TAO_EC_ObserverStrategy + * + * @brief The strategy to handle observers for the Event Channel + * subscriptions and publication. + * + * The Event Channel supports Observers for the set of + * subscriptions and publications. + * This is used to implement federations of event channels, + * either through UDP (multicast and unicast) and/or regular CORBA + * calls. + * This behavior of the EC is strategized to avoid overhead when + * no gateways are needed. + */ class TAO_RTEvent_Export TAO_EC_ObserverStrategy { - // = TITLE - // The strategy to handle observers for the Event Channel - // subscriptions and publication. - // - // = DESCRIPTION - // The Event Channel supports Observers for the set of - // subscriptions and publications. - // This is used to implement federations of event channels, - // either through UDP (multicast and unicast) and/or regular CORBA - // calls. - // - // This behavior of the EC is strategized to avoid overhead when - // no gateways are needed. - // public: + /// Destructor virtual ~TAO_EC_ObserverStrategy (void); - // Destructor + /// The basic methods to support the EC strategies. virtual RtecEventChannelAdmin::Observer_Handle append_observer (RtecEventChannelAdmin::Observer_ptr, CORBA::Environment &env) @@ -78,37 +69,37 @@ public: RtecEventChannelAdmin::EventChannel::SYNCHRONIZATION_ERROR, RtecEventChannelAdmin::EventChannel::CANT_REMOVE_OBSERVER)) = 0; - // The basic methods to support the EC strategies. + /// Used by the EC to inform the ObserverStrategy that a Consumer has + /// connected or disconnected from it. virtual void connected (TAO_EC_ProxyPushConsumer*, CORBA::Environment&) = 0; virtual void disconnected (TAO_EC_ProxyPushConsumer*, CORBA::Environment&) = 0; - // Used by the EC to inform the ObserverStrategy that a Consumer has - // connected or disconnected from it. + /// Used by the EC to inform the ObserverStrategy that a Consumer has + /// connected or disconnected from it. virtual void connected (TAO_EC_ProxyPushSupplier*, CORBA::Environment&) = 0; virtual void disconnected (TAO_EC_ProxyPushSupplier*, CORBA::Environment&) = 0; - // Used by the EC to inform the ObserverStrategy that a Consumer has - // connected or disconnected from it. }; // **************************************************************** +/** + * @class TAO_EC_Null_ObserverStrategy + * + * @brief A null observer strategy. + * + * This class keeps no information and simply ignores the messages + * from the EC. + */ class TAO_RTEvent_Export TAO_EC_Null_ObserverStrategy : public TAO_EC_ObserverStrategy { - // = TITLE - // A null observer strategy. - // - // = DESCRIPTION - // This class keeps no information and simply ignores the messages - // from the EC. - // public: + /// Constructor TAO_EC_Null_ObserverStrategy (void); - // Constructor // = The TAO_EC_ObserverStrategy methods. virtual RtecEventChannelAdmin::Observer_Handle @@ -137,29 +128,30 @@ public: // **************************************************************** +/** + * @class TAO_EC_Basic_ObserverStrategy + * + * @brief A simple observer strategy. + * + * This class simply keeps the information about the current list + * of observers, whenever the list of consumers and/or suppliers + * changes in queries the EC, computes the global subscription + * and/or publication list and sends the update message to all the + * observers. + * + * <H2>Memory Management</H2> + * It assumes ownership of the <lock>, but not of the + * Event_Channel. + */ class TAO_RTEvent_Export TAO_EC_Basic_ObserverStrategy : public TAO_EC_ObserverStrategy { - // = TITLE - // A simple observer strategy. - // - // = DESCRIPTION - // This class simply keeps the information about the current list - // of observers, whenever the list of consumers and/or suppliers - // changes in queries the EC, computes the global subscription - // and/or publication list and sends the update message to all the - // observers. - // - // = MEMORY MANAGMENT - // It assumes ownership of the <lock>, but not of the - // Event_Channel. - // public: + /// Constructor TAO_EC_Basic_ObserverStrategy (TAO_EC_Event_Channel* ec, ACE_Lock* lock); - // Constructor + /// Destructor virtual ~TAO_EC_Basic_ObserverStrategy (void); - // Destructor // = The TAO_EC_ObserverStrategy methods. virtual RtecEventChannelAdmin::Observer_Handle @@ -229,25 +221,25 @@ public: typedef ACE_RB_Tree_Iterator<RtecEventComm::EventHeader,int,Header_Compare,ACE_Null_Mutex> HeadersIterator; protected: + /// Helper functions to compute the consumer and supplier QOS. void fill_qos (RtecEventChannelAdmin::ConsumerQOS &qos, CORBA::Environment &env); void fill_qos (RtecEventChannelAdmin::SupplierQOS &qos, CORBA::Environment &env); - // Helper functions to compute the consumer and supplier QOS. protected: + /// The event channel. TAO_EC_Event_Channel* event_channel_; - // The event channel. + /// The lock ACE_Lock* lock_; - // The lock + /// The handles are generated in sequential order, but are opaque to + /// the client. RtecEventChannelAdmin::Observer_Handle handle_generator_; - // The handles are generated in sequential order, but are opaque to - // the client. + /// Keep the set of Observers Observer_Map observers_; - // Keep the set of Observers }; // **************************************************************** @@ -255,8 +247,8 @@ protected: class TAO_EC_Accumulate_Supplier_Headers : public TAO_ESF_Worker<TAO_EC_ProxyPushSupplier> { public: + /// Constructor TAO_EC_Accumulate_Supplier_Headers (TAO_EC_Basic_ObserverStrategy::Headers &headers); - // Constructor virtual void work (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &ACE_TRY_ENV); @@ -270,8 +262,8 @@ private: class TAO_EC_Accumulate_Consumer_Headers : public TAO_ESF_Worker<TAO_EC_ProxyPushConsumer> { public: + /// Constructor TAO_EC_Accumulate_Consumer_Headers (TAO_EC_Basic_ObserverStrategy::Headers &headers); - // Constructor virtual void work (TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &ACE_TRY_ENV); diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Per_Supplier_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Per_Supplier_Filter.h index 1928251d427..2dfb9c95c1e 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Per_Supplier_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Per_Supplier_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Per_Supplier_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Per_Supplier_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_PER_SUPPLIER_FILTER_H #define TAO_EC_PER_SUPPLIER_FILTER_H @@ -36,25 +26,26 @@ template<class PROXY> class TAO_ESF_Proxy_Collection; +/** + * @class TAO_EC_Per_Supplier_Filter + * + * @brief Filter the events on each supplier. + * + * This is a filtering strategy for the suppliers. In this + * particular case we keep a collection of the consumers that + * could potentially be interested in any event generated by a + * particular supplier. + * This minimizes the amount of consumers touched by the EC when + * dispatching an event. + */ class TAO_RTEvent_Export TAO_EC_Per_Supplier_Filter : public TAO_EC_Supplier_Filter { - // = TITLE - // Filter the events on each supplier. - // - // = DESCRIPTION - // This is a filtering strategy for the suppliers. In this - // particular case we keep a collection of the consumers that - // could potentially be interested in any event generated by a - // particular supplier. - // This minimizes the amount of consumers touched by the EC when - // dispatching an event. - // public: + /// Constructor TAO_EC_Per_Supplier_Filter (TAO_EC_Event_Channel* ec); - // Constructor + /// Destructor virtual ~TAO_EC_Per_Supplier_Filter (void); - // Destructor // = The TAO_EC_Supplier_Filter methods. virtual void bind (TAO_EC_ProxyPushConsumer* consumer); @@ -72,35 +63,36 @@ public: virtual CORBA::ULong _incr_refcnt (void); private: + /// The event channel, used to locate the set of consumers. TAO_EC_Event_Channel *event_channel_; - // The event channel, used to locate the set of consumers. + /// The proxy for the supplier we are bound to. TAO_EC_ProxyPushConsumer* consumer_; - // The proxy for the supplier we are bound to. + /// Keep the collection of proxies for the consumers that may be + /// interested in our events. TAO_ESF_Proxy_Collection<TAO_EC_ProxyPushSupplier>* collection_; - // Keep the collection of proxies for the consumers that may be - // interested in our events. + /// Reference counting CORBA::ULong refcnt_; - // Reference counting + /// Locking ACE_SYNCH_MUTEX lock_; - // Locking }; // **************************************************************** +/** + * @class TAO_EC_Per_Supplier_Filter_Builder + * + * @brief Create Per_Supplier_Filter objects + * + */ class TAO_RTEvent_Export TAO_EC_Per_Supplier_Filter_Builder : public TAO_EC_Supplier_Filter_Builder { - // = TITLE - // Create Per_Supplier_Filter objects - // - // = DESCRIPTION - // public: + /// constructor.... TAO_EC_Per_Supplier_Filter_Builder (TAO_EC_Event_Channel* ec); - // constructor.... // = The TAO_EC_Supplier_Filter_Builder methods... virtual TAO_EC_Supplier_Filter* @@ -109,8 +101,8 @@ public: destroy (TAO_EC_Supplier_Filter *filter); private: + /// The event channel TAO_EC_Event_Channel* event_channel_; - // The event channel }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Prefix_Filter_Builder.h b/TAO/orbsvcs/orbsvcs/Event/EC_Prefix_Filter_Builder.h index 5e20ce61d3f..02989dcc872 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Prefix_Filter_Builder.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Prefix_Filter_Builder.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Prefix_Filter_Builder -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Prefix_Filter_Builder.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_PREFIX_FILTER_BUILDER_H #define TAO_EC_PREFIX_FILTER_BUILDER_H @@ -35,22 +25,23 @@ class TAO_EC_Filter; class TAO_EC_Event_Channel; +/** + * @class TAO_EC_Prefix_Filter_Builder + * + * @brief Implement a builder for the fundamental filters. + * + * The prefix filtering mechanisms in the Event channel + * (source/type based filtering + disjunctions and conjunctions) + * are constructed using this class. + */ class TAO_RTEvent_Export TAO_EC_Prefix_Filter_Builder : public TAO_EC_Filter_Builder { - // = TITLE - // Implement a builder for the fundamental filters. - // - // = DESCRIPTION - // The prefix filtering mechanisms in the Event channel - // (source/type based filtering + disjunctions and conjunctions) - // are constructed using this class. - // public: + /// constructor. TAO_EC_Prefix_Filter_Builder (TAO_EC_Event_Channel* ec); - // constructor. + /// destructor... virtual ~TAO_EC_Prefix_Filter_Builder (void); - // destructor... // = The TAO_EC_Filter_Builder methods... TAO_EC_Filter* build (TAO_EC_ProxyPushSupplier *supplier, @@ -58,14 +49,14 @@ public: CORBA::Environment &env) const; private: + /// Recursively build the filter tree. TAO_EC_Filter* recursive_build (TAO_EC_ProxyPushSupplier *supplier, RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::ULong& pos) const; - // Recursively build the filter tree. private: + /// The event channel. TAO_EC_Event_Channel* event_channel_; - // The event channel. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Dispatching.h b/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Dispatching.h index 44cfa6d2f3e..b0e95fcf814 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Dispatching.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Dispatching.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Priority_Dispatching -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Priority_Dispatching.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_PRIORITY_DISPATCHING_H #define TAO_EC_PRIORITY_DISPATCHING_H @@ -38,27 +28,28 @@ class TAO_EC_Dispatching_Task; class TAO_EC_Event_Channel; +/** + * @class TAO_EC_Priority_Dispatching + * + * @brief Dispatching strategy that minimizes priority inversion. + * + * This strategy uses multiple queues, each serviced by a thread + * at different priority. This minimizes priority inversion + * because the consumers at higher priority are serviced before + * consumers at lower priority. + * It is more flexible than using the supplier thread to dispatch + * because it allows high-priority suppliers to push events to + * low-priority consumers (and vice-versa). + * It also isolates the supplier threads from the time spent on + * upcalls to the consumer objects, making the system easier to + * analyze and schedule. + */ class TAO_RTSchedEvent_Export TAO_EC_Priority_Dispatching : public TAO_EC_Dispatching { - // = TITLE - // Dispatching strategy that minimizes priority inversion. - // - // = DESCRIPTION - // This strategy uses multiple queues, each serviced by a thread - // at different priority. This minimizes priority inversion - // because the consumers at higher priority are serviced before - // consumers at lower priority. - // It is more flexible than using the supplier thread to dispatch - // because it allows high-priority suppliers to push events to - // low-priority consumers (and vice-versa). - // It also isolates the supplier threads from the time spent on - // upcalls to the consumer objects, making the system easier to - // analyze and schedule. - // public: + /// The scheduler is used to find the range of priorities and similar + /// info. TAO_EC_Priority_Dispatching (TAO_EC_Event_Channel* ec); - // The scheduler is used to find the range of priorities and similar - // info. // = The EC_Dispatching methods. virtual void activate (void); @@ -75,17 +66,17 @@ public: CORBA::Environment& env); private: + /// Use our own thread manager. ACE_Thread_Manager thread_manager_; - // Use our own thread manager. + /// The number of active tasks int ntasks_; - // The number of active tasks + /// The tasks.. TAO_EC_Dispatching_Task** tasks_; - // The tasks.. + /// The scheduler RtecScheduler::Scheduler_var scheduler_; - // The scheduler }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Scheduling.h b/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Scheduling.h index 1af6a4524e1..72c6cdb9095 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Scheduling.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Priority_Scheduling.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Priority_Scheduling -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Priority_Scheduling.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_PRIORITY_SCHEDULING_H #define TAO_EC_PRIORITY_SCHEDULING_H @@ -35,37 +25,36 @@ #include "orbsvcs/RtecSchedulerC.h" #include "sched_event_export.h" +/** + * @class TAO_EC_Priority_Scheduling + * + * @brief A scheduling strategy that uses TAO's real-time scheduler + * + * This implementation of the Scheduling_Strategy uses TAO's + * real-time scheduler. + */ class TAO_RTSchedEvent_Export TAO_EC_Priority_Scheduling : public TAO_EC_Scheduling_Strategy { - // = TITLE - // A scheduling strategy that uses TAO's real-time scheduler - // - // = DESCRIPTION - // This implementation of the Scheduling_Strategy uses TAO's - // real-time scheduler. - // - // = MEMORY MANAGMENT - // public: + /// Constructor. TAO_EC_Priority_Scheduling (RtecScheduler::Scheduler_ptr scheduler); - // Constructor. + /// Destructor virtual ~TAO_EC_Priority_Scheduling (void); - // Destructor + /// Add all the dependencies between <supplier> and <consumer> virtual void add_proxy_supplier_dependencies ( TAO_EC_ProxyPushSupplier *supplier, TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &ACE_TRY_ENV); - // Add all the dependencies between <supplier> and <consumer> + /// Initializes <qos_info> based on the QoS information for + /// <consumer> and the event header. virtual void init_event_qos ( const RtecEventComm::EventHeader& header, TAO_EC_ProxyPushConsumer *consumer, TAO_EC_QOS_Info& qos_info, CORBA::Environment &ACE_TRY_ENV); - // Initializes <qos_info> based on the QoS information for - // <consumer> and the event header. private: ACE_UNIMPLEMENTED_FUNC (TAO_EC_Priority_Scheduling @@ -73,12 +62,12 @@ private: ACE_UNIMPLEMENTED_FUNC (TAO_EC_Priority_Scheduling& operator= (const TAO_EC_Priority_Scheduling&)) + /// Initialize our RT_Info handle and dependencies void init_rt_info (CORBA::Environment& env); - // Initialize our RT_Info handle and dependencies private: + /// The scheduler we are going to use RtecScheduler::Scheduler_var scheduler_; - // The scheduler we are going to use }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_ProxyConsumer.h b/TAO/orbsvcs/orbsvcs/Event/EC_ProxyConsumer.h index c577b0bcd96..7b897d8e75c 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_ProxyConsumer.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_ProxyConsumer.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_ProxyConsumer -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_ProxyConsumer.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_PROXYCONSUMER_H #define TAO_EC_PROXYCONSUMER_H @@ -37,89 +27,92 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushSupplier; class TAO_EC_Supplier_Filter; +/** + * @class TAO_EC_ProxyPushConsumer + * + * @brief ProxyPushConsumer + * + * Implement the RtecEventChannelAdmin::ProxyPushConsumer interface, + * remember that this class is used to communicate with a + * PushSupplier, so, in effect, this is the ambassador for a + * supplier inside the event channel. + * + * <H2>Memory Management</H2> + * It makes a copy of the SupplierQOS and the supplier object + * reference. + * It uses bind/unbind to control the lifetime of the + * Supplier_Filter object. + * The object commits suicide when disconnect_push_consumer() is + * called. + * + * <H2>Locking</H2> + * No provisions for locking, access must be serialized + * externally. + */ class TAO_RTEvent_Export TAO_EC_ProxyPushConsumer : public POA_RtecEventChannelAdmin::ProxyPushConsumer { - // = TITLE - // ProxyPushConsumer - // - // = DESCRIPTION - // Implement the RtecEventChannelAdmin::ProxyPushConsumer interface, - // remember that this class is used to communicate with a - // PushSupplier, so, in effect, this is the ambassador for a - // supplier inside the event channel. - // - // = MEMORY MANAGMENT - // It makes a copy of the SupplierQOS and the supplier object - // reference. - // It uses bind/unbind to control the lifetime of the - // Supplier_Filter object. - // The object commits suicide when disconnect_push_consumer() is - // called. - // - // = LOCKING - // No provisions for locking, access must be serialized - // externally. - // public: typedef RtecEventChannelAdmin::ProxyPushConsumer Interface; typedef RtecEventChannelAdmin::ProxyPushConsumer_var _var_type; + /// constructor... TAO_EC_ProxyPushConsumer (TAO_EC_Event_Channel* event_channel); - // constructor... + /// destructor... virtual ~TAO_EC_ProxyPushConsumer (void); - // destructor... + /// Activate in the POA virtual RtecEventChannelAdmin::ProxyPushConsumer_ptr activate (CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // Activate in the POA + /// Deactivate from the POA void deactivate (CORBA::Environment &ACE_TRY_ENV); - // Deactivate from the POA + /// Return 0 if no supplier is connected... CORBA::Boolean is_connected (void) const; - // Return 0 if no supplier is connected... + /// Return the consumer object reference. It returns nil() if it has + /// not connected yet. RtecEventComm::PushSupplier_ptr supplier (void) const; - // Return the consumer object reference. It returns nil() if it has - // not connected yet. + /// The QoS (subscription) used to connect to the EC. const RtecEventChannelAdmin::SupplierQOS& publications (void) const; - // The QoS (subscription) used to connect to the EC. + /** + * Invoke the _non_existent() pseudo-operation on the supplier. If + * it is disconnected then it returns true and sets the + * <disconnected> flag. + */ CORBA::Boolean supplier_non_existent (CORBA::Boolean_out disconnected, CORBA::Environment &ACE_TRY_ENV); - // Invoke the _non_existent() pseudo-operation on the supplier. If - // it is disconnected then it returns true and sets the - // <disconnected> flag. + /// Concrete implementations can use this methods to keep track of + /// the consumers interested in this events. virtual void connected (TAO_EC_ProxyPushSupplier* supplier, CORBA::Environment &env); virtual void reconnected (TAO_EC_ProxyPushSupplier* supplier, CORBA::Environment &env); virtual void disconnected (TAO_EC_ProxyPushSupplier* supplier, CORBA::Environment &env); - // Concrete implementations can use this methods to keep track of - // the consumers interested in this events. + /// Usually implemented as no-ops, but some configurations may + /// require this methods. virtual void connected (TAO_EC_ProxyPushConsumer* consumer, CORBA::Environment &env); virtual void reconnected (TAO_EC_ProxyPushConsumer* consumer, CORBA::Environment &env); virtual void disconnected (TAO_EC_ProxyPushConsumer* consumer, CORBA::Environment &env); - // Usually implemented as no-ops, but some configurations may - // require this methods. + /// The event channel is shutting down virtual void shutdown (CORBA::Environment&); - // The event channel is shutting down + /// The QoS (subscription) used to connect to the EC, assumes the + /// locks are held, use with care! const RtecEventChannelAdmin::SupplierQOS& publications_i (void) const; - // The QoS (subscription) used to connect to the EC, assumes the - // locks are held, use with care! + /// Increment and decrement the reference count. CORBA::ULong _incr_refcnt (void); CORBA::ULong _decr_refcnt (void); - // Increment and decrement the reference count. // = The RtecEventChannelAdmin::ProxyPushConsumer methods... virtual void connect_push_supplier ( @@ -142,94 +135,95 @@ public: TAO_default_environment ()); protected: + /// Set the supplier, used by some implementations to change the + /// policies used when invoking operations on the supplier. void supplier (RtecEventComm::PushSupplier_ptr supplier); void supplier_i (RtecEventComm::PushSupplier_ptr supplier); - // Set the supplier, used by some implementations to change the - // policies used when invoking operations on the supplier. friend class TAO_EC_ProxyPushConsumer_Guard; // The guard needs access to the following protected methods. + /// The private version (without locking) of is_connected(). CORBA::Boolean is_connected_i (void) const; - // The private version (without locking) of is_connected(). + /// Return the current filter, assumes the locks are held. TAO_EC_Supplier_Filter *filter_i (void) const; - // Return the current filter, assumes the locks are held. + /// Release the filter and the supplier void cleanup_i (void); - // Release the filter and the supplier private: + /// The supplier admin, used for activation and memory managment. TAO_EC_Event_Channel* event_channel_; - // The supplier admin, used for activation and memory managment. + /// The locking strategy. ACE_Lock* lock_; - // The locking strategy. + /// The reference count. CORBA::ULong refcount_; - // The reference count. + /// The supplier.... RtecEventComm::PushSupplier_var supplier_; - // The supplier.... + /// If the flag is not zero then we are connected, notice that the + /// supplier can be nil. int connected_; - // If the flag is not zero then we are connected, notice that the - // supplier can be nil. + /// The publication and QoS information... RtecEventChannelAdmin::SupplierQOS qos_; - // The publication and QoS information... + /// Store the default POA. PortableServer::POA_var default_POA_; - // Store the default POA. + /// The strategy to do filtering close to the supplier TAO_EC_Supplier_Filter* filter_; - // The strategy to do filtering close to the supplier }; // **************************************************************** +/** + * @class TAO_EC_ProxyPushConsumer_Guard + * + * @brief A Guard for the ProxyPushConsumer reference count + * + * This is a helper class used in the implementation of + * ProxyPushConumer. It provides a Guard mechanism to increment + * the reference count on the proxy and its filter, eliminating + * the need to hold mutexes during long operations. + */ class TAO_RTEvent_Export TAO_EC_ProxyPushConsumer_Guard { - // = TITLE - // A Guard for the ProxyPushConsumer reference count - // - // = DESCRIPTION - // This is a helper class used in the implementation of - // ProxyPushConumer. It provides a Guard mechanism to increment - // the reference count on the proxy and its filter, eliminating - // the need to hold mutexes during long operations. - // public: + /// Constructor TAO_EC_ProxyPushConsumer_Guard (ACE_Lock *lock, CORBA::ULong &refcount, TAO_EC_Event_Channel *ec, TAO_EC_ProxyPushConsumer *proxy); - // Constructor + /// Destructor ~TAO_EC_ProxyPushConsumer_Guard (void); - // Destructor + /// Returns 1 if the reference count successfully acquired int locked (void) const; - // Returns 1 if the reference count successfully acquired TAO_EC_Supplier_Filter *filter; private: + /// The lock used to protect the reference count ACE_Lock *lock_; - // The lock used to protect the reference count + /// The reference count CORBA::ULong &refcount_; - // The reference count + /// The event channel used to destroy the proxy TAO_EC_Event_Channel *event_channel_; - // The event channel used to destroy the proxy + /// The proxy whose lifetime is controlled by the reference count TAO_EC_ProxyPushConsumer *proxy_; - // The proxy whose lifetime is controlled by the reference count + /// This flag is set to 1 if the reference count was successfully + /// acquired. int locked_; - // This flag is set to 1 if the reference count was successfully - // acquired. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_ProxySupplier.h b/TAO/orbsvcs/orbsvcs/Event/EC_ProxySupplier.h index c89fe313218..e7e1e0717b6 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_ProxySupplier.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_ProxySupplier.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_ProxySupplier -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_ProxySupplier.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_PROXYSUPPLIER_H #define TAO_EC_PROXYSUPPLIER_H @@ -36,97 +26,101 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushConsumer; +/** + * @class TAO_EC_ProxyPushSupplier + * + * @brief ProxyPushSupplier + * + * Implement the RtecEventChannelAdmin::ProxyPushSupplier interface, + * remember that this class is used to communicate with a + * PushConsumer, so, in effect, this is the ambassador for a + * consumer inside the event channel. + * + * <H2>Memory Management</H2> + * It does not assume ownership of the TAO_EC_Dispatching object. + * It makes a copy of the ConsumerQOS and the consumer object + * reference. + * + * <H2>Locking</H2> + * Locking is strategized, the event channel acts as a factory for + * the locking strategies. + * + * @todo We don't need to provide a trivial filter, the object itself + * could short-circuit the filter() ---> push() cycle when the EC + * is properly configured, we need to explore this... + */ class TAO_RTEvent_Export TAO_EC_ProxyPushSupplier : public POA_RtecEventChannelAdmin::ProxyPushSupplier, public TAO_EC_Filter { - // = TITLE - // ProxyPushSupplier - // - // = DESCRIPTION - // Implement the RtecEventChannelAdmin::ProxyPushSupplier interface, - // remember that this class is used to communicate with a - // PushConsumer, so, in effect, this is the ambassador for a - // consumer inside the event channel. - // - // = MEMORY MANAGMENT - // It does not assume ownership of the TAO_EC_Dispatching object. - // It makes a copy of the ConsumerQOS and the consumer object - // reference. - // - // = LOCKING - // Locking is strategized, the event channel acts as a factory for - // the locking strategies. - // - // = TODO - // We don't need to provide a trivial filter, the object itself - // could short-circuit the filter() ---> push() cycle when the EC - // is properly configured, we need to explore this... - // public: typedef RtecEventChannelAdmin::ProxyPushSupplier Interface; typedef RtecEventChannelAdmin::ProxyPushSupplier_var _var_type; + /// constructor... TAO_EC_ProxyPushSupplier (TAO_EC_Event_Channel* event_channel); - // constructor... + /// destructor... virtual ~TAO_EC_ProxyPushSupplier (void); - // destructor... + /// Activate in the POA virtual RtecEventChannelAdmin::ProxyPushSupplier_ptr activate (CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // Activate in the POA + /// Deactivate from the POA virtual void deactivate (CORBA::Environment &ACE_TRY_ENV) ACE_THROW_SPEC (()); - // Deactivate from the POA + /// Return 0 if no consumer is connected... CORBA::Boolean is_connected (void) const; - // Return 0 if no consumer is connected... + /// Return 1 if it is suspended. CORBA::Boolean is_suspended (void) const; - // Return 1 if it is suspended. + /** + * Return the consumer object reference. It returns nil() if it has + * not connected yet. + * NOTE: This method does not return a new reference!!! Doing so + * will increase the locking overhead on the critical path. + */ RtecEventComm::PushConsumer_ptr consumer (void) const; - // Return the consumer object reference. It returns nil() if it has - // not connected yet. - // NOTE: This method does not return a new reference!!! Doing so - // will increase the locking overhead on the critical path. + /// The QoS (subscription) used to connect to the EC. const RtecEventChannelAdmin::ConsumerQOS& subscriptions (void) const; - // The QoS (subscription) used to connect to the EC. + /// Concrete implementations can use this methods to keep track of + /// the suppliers that publish its events. virtual void connected (TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &env); virtual void reconnected (TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &env); virtual void disconnected (TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &env); - // Concrete implementations can use this methods to keep track of - // the suppliers that publish its events. + /// Usually implemented as no-ops, but some configurations may + /// require this methods. virtual void connected (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &env); virtual void reconnected (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &env); virtual void disconnected (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &env); - // Usually implemented as no-ops, but some configurations may - // require this methods. + /// The event channel is shutting down virtual void shutdown (CORBA::Environment &env); - // The event channel is shutting down + /// Pushes to the consumer, verifies that it is connected and that it + /// is not suspended. void push_to_consumer (RtecEventComm::PushConsumer_ptr consumer, const RtecEventComm::EventSet &event, CORBA::Environment &env); void reactive_push_to_consumer (RtecEventComm::PushConsumer_ptr consumer, const RtecEventComm::EventSet &event, CORBA::Environment &env); - // Pushes to the consumer, verifies that it is connected and that it - // is not suspended. + /** + * Invoke the _non_existent() pseudo-operation on the consumer. If + * it is disconnected then it returns true and sets the + * <disconnected> flag. + */ CORBA::Boolean consumer_non_existent (CORBA::Boolean_out disconnected, CORBA::Environment &ACE_TRY_ENV); - // Invoke the _non_existent() pseudo-operation on the consumer. If - // it is disconnected then it returns true and sets the - // <disconnected> flag. // = The RtecEventChannelAdmin::ProxyPushSupplier methods... virtual void connect_push_consumer ( @@ -143,9 +137,9 @@ public: virtual void resume_connection (CORBA::Environment &) ACE_THROW_SPEC ((CORBA::SystemException)); + /// Increment and decrement the reference count. CORBA::ULong _incr_refcnt (void); CORBA::ULong _decr_refcnt (void); - // Increment and decrement the reference count. // = The TAO_EC_Filter methods, only push() is implemented... virtual int filter (const RtecEventComm::EventSet &event, @@ -173,41 +167,41 @@ public: virtual void _remove_ref (CORBA_Environment &ACE_TRY_ENV); protected: + /// Set the consumer, used by some implementations to change the + /// policies used when invoking operations on the consumer. void consumer (RtecEventComm::PushConsumer_ptr consumer); void consumer_i (RtecEventComm::PushConsumer_ptr consumer); - // Set the consumer, used by some implementations to change the - // policies used when invoking operations on the consumer. + /// The private version (without locking) of is_connected(). CORBA::Boolean is_connected_i (void) const; - // The private version (without locking) of is_connected(). + /// Release the child and the consumer void cleanup_i (void); - // Release the child and the consumer private: + /// The Event Channel that owns this object. TAO_EC_Event_Channel* event_channel_; - // The Event Channel that owns this object. + /// The locking strategy. ACE_Lock* lock_; - // The locking strategy. + /// The reference count. CORBA::ULong refcount_; - // The reference count. + /// The consumer.... RtecEventComm::PushConsumer_var consumer_; - // The consumer.... + /// Is this consumer suspended? CORBA::Boolean suspended_; - // Is this consumer suspended? + /// The subscription and QoS information... RtecEventChannelAdmin::ConsumerQOS qos_; - // The subscription and QoS information... + /// Store the default POA. PortableServer::POA_var default_POA_; - // Store the default POA. + /// The filter object TAO_EC_Filter* child_; - // The filter object }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_QOS_Info.h b/TAO/orbsvcs/orbsvcs/Event/EC_QOS_Info.h index de579c533c7..9b8b51274bf 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_QOS_Info.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_QOS_Info.h @@ -1,25 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Event_Channel -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// ============================================================================ +/** + * @file EC_Event_Channel.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_QOS_INFO_H #define TAO_EC_QOS_INFO_H @@ -32,32 +23,35 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_QOS_Info + * + * @brief A representation of QoS information for the event channel + * filters. + * + * Filters compute QOS information for real-time dispatching, this + * class encapsulates that information. + * This first implementation is just a place-holder. + */ class TAO_RTEvent_Export TAO_EC_QOS_Info { - // = TITLE - // A representation of QoS information for the event channel - // filters. - // - // = DESCRIPTION - // Filters compute QOS information for real-time dispatching, this - // class encapsulates that information. - // This first implementation is just a place-holder. - // public: + /// constructor TAO_EC_QOS_Info (void); - // constructor + /// copy constructor, it does the obvious thing, but if it is not + /// here the HP/aCC compiler breaks. TAO_EC_QOS_Info (const TAO_EC_QOS_Info &rhs); - // copy constructor, it does the obvious thing, but if it is not - // here the HP/aCC compiler breaks. RtecBase::handle_t rt_info; RtecBase::Preemption_Priority_t preemption_priority; + /** + * Timer ids propagate their identity using this field, notice that + * they cannot use the event type because there could be multiple + * timeouts for the same consumer. + */ long timer_id_; - // Timer ids propagate their identity using this field, notice that - // they cannot use the event type because there could be multiple - // timeouts for the same consumer. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_ConsumerControl.h b/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_ConsumerControl.h index 484879e36df..4211195af02 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_ConsumerControl.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_ConsumerControl.h @@ -1,21 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Reactive_ConsumerControl -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// More details can be found in: -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file EC_Reactive_ConsumerControl.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_REACTIVE_CONSUMERCONTROL_H #define TAO_EC_REACTIVE_CONSUMERCONTROL_H @@ -34,57 +29,53 @@ class TAO_EC_Event_Channel; class TAO_EC_Reactive_ConsumerControl; +/** + * @class TAO_EC_ConsumerControl_Adapter + * + * @brief Forwards timeout events to the Reactive ConsumerControl + * + * The Reactive ConsumerControl strategy uses the reactor to + * periodically wakeup and verify the state of the consumers + * registered with the Event Channel. + */ class TAO_RTEvent_Export TAO_EC_ConsumerControl_Adapter : public ACE_Event_Handler { - // = TITLE - // Forwards timeout events to the Reactive ConsumerControl - // - // = DESCRIPTION - // The Reactive ConsumerControl strategy uses the reactor to - // periodically wakeup and verify the state of the consumers - // registered with the Event Channel. - // public: + /// Constructor TAO_EC_ConsumerControl_Adapter (TAO_EC_Reactive_ConsumerControl *adaptee); - // Constructor // = Documented in ACE_Event_Handler. virtual int handle_timeout (const ACE_Time_Value &tv, const void *arg = 0); private: + /// The adapted object TAO_EC_Reactive_ConsumerControl *adaptee_; - // The adapted object }; +/** + * @class TAO_EC_Reactive_ConsumerControl + * + * @brief ConsumerControl + * + * Defines the interface for the consumer control strategy. + * This strategy handles misbehaving or failing consumers. + */ class TAO_RTEvent_Export TAO_EC_Reactive_ConsumerControl : public TAO_EC_ConsumerControl { - // = TITLE - // ConsumerControl - // - // = DESCRIPTION - // Defines the interface for the consumer control strategy. - // This strategy handles misbehaving or failing consumers. - // - // = MEMORY MANAGMENT - // - // = LOCKING - // - // = TODO - // public: + /// Constructor. It does not assume ownership of the <event_channel> + /// parameter. TAO_EC_Reactive_ConsumerControl (const ACE_Time_Value &rate, TAO_EC_Event_Channel *event_channel, CORBA::ORB_ptr orb); - // Constructor. It does not assume ownership of the <event_channel> - // parameter. + /// destructor... virtual ~TAO_EC_Reactive_ConsumerControl (void); - // destructor... + /// Receive the timeout from the adapter void handle_timeout (const ACE_Time_Value &tv, const void* arg); - // Receive the timeout from the adapter // = Documented in TAO_EC_ConsumerControl virtual int activate (void); @@ -96,31 +87,31 @@ public: CORBA::Environment &); private: + /// Check if the consumers still exists. It is a helper method for + /// handle_timeout() to isolate the exceptions. void query_consumers (CORBA::Environment &ACE_TRY_ENV); - // Check if the consumers still exists. It is a helper method for - // handle_timeout() to isolate the exceptions. private: + /// The polling rate ACE_Time_Value rate_; - // The polling rate + /// The Adapter for the reactor events TAO_EC_ConsumerControl_Adapter adapter_; - // The Adapter for the reactor events + /// The event channel TAO_EC_Event_Channel *event_channel_; - // The event channel + /// The ORB CORBA::ORB_var orb_; - // The ORB + /// To control the timeout policy in the thread CORBA::PolicyCurrent_var policy_current_; - // To control the timeout policy in the thread + /// Precomputed policy list to the set timeout. CORBA::PolicyList policy_list_; - // Precomputed policy list to the set timeout. + /// The ORB reactor ACE_Reactor *reactor_; - // The ORB reactor }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_SupplierControl.h b/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_SupplierControl.h index 42b29564e77..4d433c04056 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_SupplierControl.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_SupplierControl.h @@ -1,21 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Reactive_SupplierControl -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// More details can be found in: -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file EC_Reactive_SupplierControl.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_REACTIVE_SUPPLIERCONTROL_H #define TAO_EC_REACTIVE_SUPPLIERCONTROL_H @@ -34,57 +29,53 @@ class TAO_EC_Event_Channel; class TAO_EC_Reactive_SupplierControl; +/** + * @class TAO_EC_SupplierControl_Adapter + * + * @brief Forwards timeout events to the Reactive SupplierControl + * + * The Reactive SupplierControl strategy uses the reactor to + * periodically wakeup and verify the state of the suppliers + * registered with the Event Channel. + */ class TAO_RTEvent_Export TAO_EC_SupplierControl_Adapter : public ACE_Event_Handler { - // = TITLE - // Forwards timeout events to the Reactive SupplierControl - // - // = DESCRIPTION - // The Reactive SupplierControl strategy uses the reactor to - // periodically wakeup and verify the state of the suppliers - // registered with the Event Channel. - // public: + /// Constructor TAO_EC_SupplierControl_Adapter (TAO_EC_Reactive_SupplierControl *adaptee); - // Constructor // = Documented in ACE_Event_Handler. virtual int handle_timeout (const ACE_Time_Value &tv, const void *arg = 0); private: + /// The adapted object TAO_EC_Reactive_SupplierControl *adaptee_; - // The adapted object }; +/** + * @class TAO_EC_Reactive_SupplierControl + * + * @brief SupplierControl + * + * Defines the interface for the supplier control strategy. + * This strategy handles misbehaving or failing suppliers. + */ class TAO_RTEvent_Export TAO_EC_Reactive_SupplierControl : public TAO_EC_SupplierControl { - // = TITLE - // SupplierControl - // - // = DESCRIPTION - // Defines the interface for the supplier control strategy. - // This strategy handles misbehaving or failing suppliers. - // - // = MEMORY MANAGMENT - // - // = LOCKING - // - // = TODO - // public: + /// Constructor. It does not assume ownership of the <event_channel> + /// parameter. TAO_EC_Reactive_SupplierControl (const ACE_Time_Value &rate, TAO_EC_Event_Channel *event_channel, CORBA::ORB_ptr orb); - // Constructor. It does not assume ownership of the <event_channel> - // parameter. + /// destructor... virtual ~TAO_EC_Reactive_SupplierControl (void); - // destructor... + /// Receive the timeout from the adapter void handle_timeout (const ACE_Time_Value &tv, const void* arg); - // Receive the timeout from the adapter // = Documented in TAO_EC_SupplierControl virtual int activate (void); @@ -96,31 +87,31 @@ public: CORBA::Environment &); private: + /// Check if the suppliers still exists. It is a helper method for + /// handle_timeout() to isolate the exceptions. void query_suppliers (CORBA::Environment &ACE_TRY_ENV); - // Check if the suppliers still exists. It is a helper method for - // handle_timeout() to isolate the exceptions. private: + /// The polling rate ACE_Time_Value rate_; - // The polling rate + /// The Adapter for the reactor events TAO_EC_SupplierControl_Adapter adapter_; - // The Adapter for the reactor events + /// The event channel TAO_EC_Event_Channel *event_channel_; - // The event channel + /// The ORB CORBA::ORB_var orb_; - // The ORB + /// To control the timeout policy in the thread CORBA::PolicyCurrent_var policy_current_; - // To control the timeout policy in the thread + /// Precomputed policy list to the set timeout. CORBA::PolicyList policy_list_; - // Precomputed policy list to the set timeout. + /// The ORB reactor ACE_Reactor *reactor_; - // The ORB reactor }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_Timeout_Generator.h b/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_Timeout_Generator.h index 404cdd2533c..f62e58d0ec3 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_Timeout_Generator.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Reactive_Timeout_Generator.h @@ -1,27 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Reactive_Timeout_Generator -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = DESCRIPTION -// A new implementation of the Real Time Event Services. -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Reactive_Timeout_Generator.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_REACTIVE_TIMEOUT_GENERATOR_H #define TAO_EC_REACTIVE_TIMEOUT_GENERATOR_H @@ -33,23 +22,24 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Reactive_Timeout_Generator + * + * @brief A simple implementation of the Timeout_Generator based on the + * Reactor. + * + * Implements the Timeout_Generator using an ACE_Reactor. Usually + * the same reactor that is used by the ORB where the EC runs. + */ class TAO_RTEvent_Export TAO_EC_Reactive_Timeout_Generator : public TAO_EC_Timeout_Generator { - // = TITLE - // A simple implementation of the Timeout_Generator based on the - // Reactor. - // - // = DESCRIPTION - // Implements the Timeout_Generator using an ACE_Reactor. Usually - // the same reactor that is used by the ORB where the EC runs. - // public: + /// Constructor. + /// If <reactor> is 0 then we use the reactor in the ORB singleton. TAO_EC_Reactive_Timeout_Generator (ACE_Reactor *reactor = 0); - // Constructor. - // If <reactor> is 0 then we use the reactor in the ORB singleton. + /// destructor virtual ~TAO_EC_Reactive_Timeout_Generator (void); - // destructor // = The TAO_EC_Timeout_Generator methods. virtual void activate (void); @@ -61,11 +51,11 @@ public: int id); private: + /// The reactor ACE_Reactor *reactor_; - // The reactor + /// An adapter to receive the timeout events. TAO_EC_Timeout_Adapter event_handler_; - // An adapter to receive the timeout events. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Factory.h b/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Factory.h index 1ceb73d3d2c..36e79ac75cd 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Factory.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Factory.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Sched_Factory -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Sched_Factory.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SCHED_FACTORY_H #define TAO_EC_SCHED_FACTORY_H @@ -34,21 +24,20 @@ #include "sched_event_export.h" +/** + * @class TAO_EC_Sched_Factory + * + * @brief Extend the default factory to support scheduling + * + */ class TAO_RTSchedEvent_Export TAO_EC_Sched_Factory : public TAO_EC_Default_Factory { - // = TITLE - // Extend the default factory to support scheduling - // - // = DESCRIPTION - // - // = MEMORY MANAGMENT - // public: + /// Constructor TAO_EC_Sched_Factory (void); - // Constructor + /// destructor... virtual ~TAO_EC_Sched_Factory (void); - // destructor... // = The Service_Object entry points virtual int init (int argc, char* argv[]); diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter.h index d44249748a6..f0f63b3f37c 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Sched_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Sched_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SCHED_FILTER_H #define TAO_EC_SCHED_FILTER_H @@ -35,21 +25,27 @@ #include "orbsvcs/RtecSchedulerC.h" #include "sched_event_export.h" +/** + * @class TAO_EC_Sched_Filter + * + * @brief Decorate a filter with scheduling information + * + * This filter decorates a regular filter with scheduling + * information. It creates a new RT_Info entry for the filter and + * it adds the dependencies between the filter and any childrens + * it may have. + * + * <H2>Memory Management</H2> + * It assumes ownership of the children. + */ class TAO_RTSchedEvent_Export TAO_EC_Sched_Filter : public TAO_EC_Filter { - // = TITLE - // Decorate a filter with scheduling information - // - // = DESCRIPTION - // This filter decorates a regular filter with scheduling - // information. It creates a new RT_Info entry for the filter and - // it adds the dependencies between the filter and any childrens - // it may have. - // - // = MEMORY MANAGMENT - // It assumes ownership of the children. - // public: + /** + * Constructor. + * It assumes ownership of the <body>, makes a copy of the other + * parameters + */ TAO_EC_Sched_Filter (const char* name, RtecScheduler::handle_t rt_info, RtecScheduler::Scheduler_ptr scheduler, @@ -57,12 +53,9 @@ public: RtecScheduler::handle_t body_info, RtecScheduler::handle_t parent_info, RtecScheduler::Info_Type_t info_type); - // Constructor. - // It assumes ownership of the <body>, makes a copy of the other - // parameters + /// Destructor virtual ~TAO_EC_Sched_Filter (void); - // Destructor // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -96,37 +89,37 @@ private: ACE_UNIMPLEMENTED_FUNC (TAO_EC_Sched_Filter& operator= (const TAO_EC_Sched_Filter&)) + /// Initialize our RT_Info handle and dependencies void init_rt_info (CORBA::Environment& env); - // Initialize our RT_Info handle and dependencies + /// Compute a new qos_info to push up. void compute_qos_info (TAO_EC_QOS_Info& qos_info, CORBA::Environment &ACE_TRY_ENV); - // Compute a new qos_info to push up. private: + /// The RT_Info handle for this object RtecScheduler::handle_t rt_info_; - // The RT_Info handle for this object + /// Has the Scheduler been updated? int rt_info_computed_; - // Has the Scheduler been updated? + /// Our operation name ACE_CString name_; - // Our operation name + /// The scheduler we are going to use RtecScheduler::Scheduler_var scheduler_; - // The scheduler we are going to use + /// The implementation TAO_EC_Filter* body_; - // The implementation + /// The RT_Info handle for the body RtecScheduler::handle_t body_info_; - // The RT_Info handle for the body + /// The RT_Info handle for the parent RtecScheduler::handle_t parent_info_; - // The RT_Info handle for the parent + /// Required for the scheduling service RtecScheduler::Info_Type_t info_type_; - // Required for the scheduling service }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter_Builder.h b/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter_Builder.h index 218ce4a7ca2..ddf3604bc51 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter_Builder.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Sched_Filter_Builder.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Sched_Filter_Builder -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Sched_Filter_Builder.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SCHED_FILTER_BUILDER_H #define TAO_EC_SCHED_FILTER_BUILDER_H @@ -37,22 +27,23 @@ class TAO_EC_Filter; class TAO_EC_Event_Channel; +/** + * @class TAO_EC_Sched_Filter_Builder + * + * @brief Implement a builder for the fundamental filters. + * + * The sched filtering mechanisms in the Event channel + * (source/type based filtering + disjunctions and conjunctions) + * are constructed using this class. + */ class TAO_RTSchedEvent_Export TAO_EC_Sched_Filter_Builder : public TAO_EC_Filter_Builder { - // = TITLE - // Implement a builder for the fundamental filters. - // - // = DESCRIPTION - // The sched filtering mechanisms in the Event channel - // (source/type based filtering + disjunctions and conjunctions) - // are constructed using this class. - // public: + /// constructor. TAO_EC_Sched_Filter_Builder (TAO_EC_Event_Channel* ec); - // constructor. + /// destructor... virtual ~TAO_EC_Sched_Filter_Builder (void); - // destructor... // = The TAO_EC_Filter_Builder methods... TAO_EC_Filter* build (TAO_EC_ProxyPushSupplier *supplier, @@ -60,29 +51,29 @@ public: CORBA::Environment &env) const; private: + /// Recursively build the filter tree. TAO_EC_Filter* recursive_build (TAO_EC_ProxyPushSupplier *supplier, RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::ULong& pos, RtecScheduler::Scheduler_ptr scheduler, RtecScheduler::handle_t parent_info, CORBA::Environment& env) const; - // Recursively build the filter tree. + /// Build the name recursively... void recursive_name (RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::ULong& pos, RtecScheduler::Scheduler_ptr scheduler, ACE_CString &name, CORBA::Environment& env) const; - // Build the name recursively... + /// Count the number of children of the current node, i.e. until a + /// conjunction or disjunction starts. CORBA::ULong count_children (RtecEventChannelAdmin::ConsumerQOS& qos, CORBA::ULong pos) const; - // Count the number of children of the current node, i.e. until a - // conjunction or disjunction starts. private: + /// The event channel. TAO_EC_Event_Channel* event_channel_; - // The event channel. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Scheduling_Strategy.h b/TAO/orbsvcs/orbsvcs/Event/EC_Scheduling_Strategy.h index 2ea387f17d6..f846795fe9d 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Scheduling_Strategy.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Scheduling_Strategy.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Scheduling_Strategy -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Scheduling_Strategy.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SCHEDULING_STRATEGY_H #define TAO_EC_SCHEDULING_STRATEGY_H @@ -37,38 +27,36 @@ class TAO_EC_ProxyPushConsumer; class TAO_EC_ProxyPushSupplier; class TAO_EC_QOS_Info; +/** + * @class TAO_EC_Scheduling_Strategy + * + * @brief Define the interface for the scheduling strategy + * + * The scheduling strategy controls the actions that the event + * channel must take to update the dependency information in the + * scheduler and to query the scheduler for the priority of each + * event pushed by a supplier. + * The base + */ class TAO_RTEvent_Export TAO_EC_Scheduling_Strategy { - // = TITLE - // Define the interface for the scheduling strategy - // - // = DESCRIPTION - // The scheduling strategy controls the actions that the event - // channel must take to update the dependency information in the - // scheduler and to query the scheduler for the priority of each - // event pushed by a supplier. - // - // The base - // - // = MEMORY MANAGMENT - // public: + /// Destructor virtual ~TAO_EC_Scheduling_Strategy (void); - // Destructor + /// Add all the dependencies between <supplier> and <consumer> virtual void add_proxy_supplier_dependencies ( TAO_EC_ProxyPushSupplier *supplier, TAO_EC_ProxyPushConsumer *consumer, CORBA::Environment &ACE_TRY_ENV) = 0; - // Add all the dependencies between <supplier> and <consumer> + /// Initializes <qos_info> based on the QoS information for + /// <consumer> and the event header. virtual void init_event_qos ( const RtecEventComm::EventHeader& header, TAO_EC_ProxyPushConsumer *consumer, TAO_EC_QOS_Info& qos_info, CORBA::Environment &ACE_TRY_ENV) = 0; - // Initializes <qos_info> based on the QoS information for - // <consumer> and the event header. }; diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_SupplierAdmin.h b/TAO/orbsvcs/orbsvcs/Event/EC_SupplierAdmin.h index 87d52e07c1f..5276ac001f3 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_SupplierAdmin.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_SupplierAdmin.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_SupplierAdmin -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_SupplierAdmin.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SUPPLIERADMIN_H #define TAO_EC_SUPPLIERADMIN_H @@ -38,27 +28,25 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushSupplier; +/** + * @class TAO_EC_SupplierAdmin + * + * @brief Implement the RtecEventChannelAdmin::SupplierAdmin interface. + * + * + * <H2>Memory Management</H2> + * It does not assume ownership of the TAO_EC_Event_Channel object + */ class TAO_RTEvent_Export TAO_EC_SupplierAdmin : public POA_RtecEventChannelAdmin::SupplierAdmin , public TAO_ESF_Peer_Admin<TAO_EC_Event_Channel,TAO_EC_ProxyPushConsumer,RtecEventChannelAdmin::ProxyPushConsumer,TAO_EC_ProxyPushSupplier> { - // = TITLE - // ProxyPushSupplier - // - // = DESCRIPTION - // Implement the RtecEventChannelAdmin::SupplierAdmin interface. - // This class is an Abstract Factory for the - // TAO_EC_ProxyPushConsumer. - // - // = MEMORY MANAGMENT - // It does not assume ownership of the TAO_EC_Event_Channel object - // public: + /// constructor... TAO_EC_SupplierAdmin (TAO_EC_Event_Channel* event_channel); - // constructor... + /// destructor... virtual ~TAO_EC_SupplierAdmin (void); - // destructor... // = The RtecEventChannelAdmin::SupplierAdmin methods... virtual RtecEventChannelAdmin::ProxyPushConsumer_ptr @@ -69,8 +57,8 @@ public: virtual PortableServer::POA_ptr _default_POA (CORBA::Environment& env); private: + /// Store the default POA. PortableServer::POA_var default_POA_; - // Store the default POA. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_SupplierControl.h b/TAO/orbsvcs/orbsvcs/Event/EC_SupplierControl.h index 34200339341..85603bc872e 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_SupplierControl.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_SupplierControl.h @@ -1,21 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_SupplierControl -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// More details can be found in: -// http://www.cs.wustl.edu/~coryan/EC/index.html -// -// ============================================================================ +/** + * @file EC_SupplierControl.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SUPPLIERCONTROL_H #define TAO_EC_SUPPLIERCONTROL_H @@ -32,39 +27,36 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushConsumer; +/** + * @class TAO_EC_SupplierControl + * + * @brief SupplierControl + * + * Defines the interface for the supplier control strategy. + * This strategy handles misbehaving or failing suppliers. + */ class TAO_RTEvent_Export TAO_EC_SupplierControl { - // = TITLE - // SupplierControl - // - // = DESCRIPTION - // Defines the interface for the supplier control strategy. - // This strategy handles misbehaving or failing suppliers. - // - // = MEMORY MANAGMENT - // - // = LOCKING - // - // = TODO - // public: + /// Constructor. It does not assume ownership of the <event_channel> + /// parameter. TAO_EC_SupplierControl (void); - // Constructor. It does not assume ownership of the <event_channel> - // parameter. + /// destructor... virtual ~TAO_EC_SupplierControl (void); - // destructor... + /// Activate any internal threads or timers used to poll the state of + /// the suppliers virtual int activate (void); virtual int shutdown (void); - // Activate any internal threads or timers used to poll the state of - // the suppliers + /** + * Invoked by helper classes when they detect that a supplier does + * not exists (i.e. _non_existent() returns true and/or the + * CORBA::OBJECT_NOT_EXIST exception has been raised). + */ virtual void supplier_not_exist (TAO_EC_ProxyPushConsumer *proxy, CORBA::Environment &); - // Invoked by helper classes when they detect that a supplier does - // not exists (i.e. _non_existent() returns true and/or the - // CORBA::OBJECT_NOT_EXIST exception has been raised). }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter.h index 711f48363f0..d31a3e4081d 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter.h @@ -1,30 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Supplier_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = DESCRIPTION -// Define the TAO_EC_Supplier_Filter interface and some simple -// implementations. -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Supplier_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SUPPLIER_FILTER_H #define TAO_EC_SUPPLIER_FILTER_H @@ -43,83 +29,85 @@ class TAO_EC_ProxyPushConsumer; class TAO_EC_Event_Channel; class TAO_EC_QOS_Info; +/** + * @class TAO_EC_Supplier_Filter + * + * @brief The strategy to filter close to the supplier. + * + * After an event is received by the a ProxyPushConsumer it must + * be dispatched to the right set of ProxyPushSuppliers; + * determining this set is the task of this class. + * Notice that this is in fact a filter, and enforces (in part) + * the subscriptions and publications of the Event Service + * clients. + * Several implementations are possible: + * - Each ProxyPushConsumer keeps a list of ProxyPushSuppliers, + * using the subscriptions and publications to find potential + * matches. + * - Each ProxyPushConsumer keeps several such lists, indexed by + * event type and/or source, this has the advantage of further + * minimizing the set of ProxyPushSuppliers invoked. + * - A single list of consumers is kept (global for the event + * channel), such a list results is faster updates and requires + * an smaller memory footprint. + * - Multiple global lists are kept, indexed by type and/or + * source, this is a tradeoff between the solutions above. + * - No list is kept, the events are sent to the consumers which + * must filter out what they want, this is good when no + * filtering is wanted or when the amount of filtering is coarse + * i.e. each event goes to a large subset of the + * ProxyPushSuppliers. + * Different applications will require to use different + * implementations of this class; as usual the EC_Factory will + * create the right instance. + */ class TAO_RTEvent_Export TAO_EC_Supplier_Filter { - // = TITLE - // The strategy to filter close to the supplier. - // - // = DESCRIPTION - // After an event is received by the a ProxyPushConsumer it must - // be dispatched to the right set of ProxyPushSuppliers; - // determining this set is the task of this class. - // Notice that this is in fact a filter, and enforces (in part) - // the subscriptions and publications of the Event Service - // clients. - // - // Several implementations are possible: - // - // - Each ProxyPushConsumer keeps a list of ProxyPushSuppliers, - // using the subscriptions and publications to find potential - // matches. - // - Each ProxyPushConsumer keeps several such lists, indexed by - // event type and/or source, this has the advantage of further - // minimizing the set of ProxyPushSuppliers invoked. - // - A single list of consumers is kept (global for the event - // channel), such a list results is faster updates and requires - // an smaller memory footprint. - // - Multiple global lists are kept, indexed by type and/or - // source, this is a tradeoff between the solutions above. - // - No list is kept, the events are sent to the consumers which - // must filter out what they want, this is good when no - // filtering is wanted or when the amount of filtering is coarse - // i.e. each event goes to a large subset of the - // ProxyPushSuppliers. - // - // Different applications will require to use different - // implementations of this class; as usual the EC_Factory will - // create the right instance. - // public: + /// Destructor virtual ~TAO_EC_Supplier_Filter (void); - // Destructor + /** + * Whenever a ProxyPushConsumer is initialized it calls this method + * to inform the Supplier_Filter of its identity. + * Strategies that do not keep ProxyPushConsumer specific + * information, or that are shared between multiple + * ProxyPushConsumers can ignore this message. + */ virtual void bind (TAO_EC_ProxyPushConsumer* consumer) = 0; - // Whenever a ProxyPushConsumer is initialized it calls this method - // to inform the Supplier_Filter of its identity. - // Strategies that do not keep ProxyPushConsumer specific - // information, or that are shared between multiple - // ProxyPushConsumers can ignore this message. + /** + * Wheneve a ProxyPushConsumer is about to be destroyed it calls + * this method to inform the Supplier_Filter that it should + * release any resources related to it. + * Supplier_Filter strategies that are bound to a particular + * ProxyConsumer can use this opportunity to destroy themselves; + * filter strategies that do not keep ProxyPushConsumer specific + * information can simply ignore the message. + */ virtual void unbind (TAO_EC_ProxyPushConsumer* consumer) = 0; - // Wheneve a ProxyPushConsumer is about to be destroyed it calls - // this method to inform the Supplier_Filter that it should - // release any resources related to it. - // Supplier_Filter strategies that are bound to a particular - // ProxyConsumer can use this opportunity to destroy themselves; - // filter strategies that do not keep ProxyPushConsumer specific - // information can simply ignore the message. + /// Concrete implementations can use this methods to keep track of + /// the consumers interested in this events. virtual void connected (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &env) = 0; virtual void reconnected (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &env) = 0; virtual void disconnected (TAO_EC_ProxyPushSupplier *supplier, CORBA::Environment &env) = 0; - // Concrete implementations can use this methods to keep track of - // the consumers interested in this events. + /// The event channel is shutting down. virtual void shutdown (CORBA::Environment &env) = 0; - // The event channel is shutting down. + /// The ProxyPushConsumer delegates on this class to actually send + /// the event. virtual void push (const RtecEventComm::EventSet &event, CORBA::Environment &) = 0; - // The ProxyPushConsumer delegates on this class to actually send - // the event. + /// Increment and decrement the reference count, locking must be + /// provided by the user. virtual CORBA::ULong _incr_refcnt (void) = 0; virtual CORBA::ULong _decr_refcnt (void) = 0; - // Increment and decrement the reference count, locking must be - // provided by the user. }; // **************************************************************** @@ -134,11 +122,11 @@ public: CORBA::Environment &ACE_TRY_ENV); private: + /// The event we push on each case, use a reference to avoid copies. RtecEventComm::EventSet &event_; - // The event we push on each case, use a reference to avoid copies. + /// The QoS info propagated on each event. const TAO_EC_QOS_Info &event_info_; - // The QoS info propagated on each event. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter_Builder.h b/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter_Builder.h index a187d734dc9..e0806db62b2 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter_Builder.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Supplier_Filter_Builder.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Supplier_Filter_Builder -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Supplier_Filter_Builder.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_SUPPLIER_FILTER_BUILDER_H #define TAO_EC_SUPPLIER_FILTER_BUILDER_H @@ -36,29 +26,31 @@ class TAO_EC_Supplier_Filter; class TAO_EC_ProxyPushConsumer; +/** + * @class TAO_EC_Supplier_Filter_Builder + * + * @brief Abstract base class for the supplier filter builders. + * + * The creation of the right filter for each supplier controlled + * by a Supplier_Filter_Builder. + */ class TAO_RTEvent_Export TAO_EC_Supplier_Filter_Builder { - // = TITLE - // Abstract base class for the supplier filter builders. - // - // = DESCRIPTION - // The creation of the right filter for each supplier controlled - // by a Supplier_Filter_Builder. - // - // public: + /// destructor... virtual ~TAO_EC_Supplier_Filter_Builder (void); - // destructor... + /** + * Create the filter. The <consumer> is bound to the returned + * Supplier_Filter, it must be <unbound> upon destruction and/or + * disconnection. + */ virtual TAO_EC_Supplier_Filter* create (RtecEventChannelAdmin::SupplierQOS& qos) = 0; - // Create the filter. The <consumer> is bound to the returned - // Supplier_Filter, it must be <unbound> upon destruction and/or - // disconnection. + /// The user is returning the filter for destruction/recycling. virtual void destroy (TAO_EC_Supplier_Filter *filter) = 0; - // The user is returning the filter for destruction/recycling. }; // **************************************************************** diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Filter.h index cd49fc1f5c9..7b3a151eabd 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Timeout_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Timeout_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_TIMEOUT_FILTER_H #define TAO_EC_TIMEOUT_FILTER_H @@ -37,36 +27,37 @@ class TAO_EC_Event_Channel; class TAO_EC_ProxyPushSupplier; +/** + * @class TAO_EC_Timeout_Filter + * + * @brief A filter based on event type/source + * + * This filter only accept events with a predefined type/source, + * both the source and the type can be wildcards. + */ class TAO_RTEvent_Export TAO_EC_Timeout_Filter : public TAO_EC_Filter { - // = TITLE - // A filter based on event type/source - // - // = DESCRIPTION - // This filter only accept events with a predefined type/source, - // both the source and the type can be wildcards. - // public: + /// Constructor. TAO_EC_Timeout_Filter (TAO_EC_Event_Channel *event_channel, TAO_EC_ProxyPushSupplier *supplier, const TAO_EC_QOS_Info& qos_info, RtecEventComm::EventType type, RtecEventComm::Time period); - // Constructor. + /// Destructor. virtual ~TAO_EC_Timeout_Filter (void); - // Destructor. + /// Return the QOS_Info for this Timeout filter. const TAO_EC_QOS_Info& qos_info (void) const; - // Return the QOS_Info for this Timeout filter. + /// The type of timeout event that we generate. RtecEventComm::EventType type (void) const; - // The type of timeout event that we generate. + /// Callback from the Timeout_Generator void push_to_proxy (const RtecEventComm::EventSet& event, TAO_EC_QOS_Info& qos_info, CORBA::Environment& ACE_TRY_ENV); - // Callback from the Timeout_Generator // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -96,24 +87,24 @@ private: (const TAO_EC_Timeout_Filter&)) private: + /// The event channel. TAO_EC_Event_Channel* event_channel_; - // The event channel. + /// The supplier that finally receives the timeout event. TAO_EC_ProxyPushSupplier *supplier_; - // The supplier that finally receives the timeout event. + /// Events "generated" by this filter use this QOS_Info. TAO_EC_QOS_Info qos_info_; - // Events "generated" by this filter use this QOS_Info. + /// The type of timeout event... RtecEventComm::EventType type_; - // The type of timeout event... + /// The period for deadline timeouts... RtecEventComm::Time period_; - // The period for deadline timeouts... + /// The ID of the timeout in the Timeout_Generator, for + /// cancellation. long id_; - // The ID of the timeout in the Timeout_Generator, for - // cancellation. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Generator.h b/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Generator.h index cb780f373f0..514a9dfe84f 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Generator.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Timeout_Generator.h @@ -1,27 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Timeout_Generator -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = DESCRIPTION -// A new implementation of the Real Time Event Services. -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Timeout_Generator.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_TIMEOUT_GENERATOR_H #define TAO_EC_TIMEOUT_GENERATOR_H @@ -38,61 +27,63 @@ class TAO_EC_QOS_Info; +/** + * @class TAO_EC_Timeout_Generator + * + * @brief Define the interface for the generators of timeout events. + * + * The Event Channel can use several strategies to dispatch + * timers, for instance, it can use the ORB reactor or a pool of + * reactors running at different priorities or a pool of + * Thread_Timer_Queue_Adapters running at different priorities + * also. + * This class is the abstract base class to abstract this + * strategies. + */ class TAO_RTEvent_Export TAO_EC_Timeout_Generator { - // = TITLE - // Define the interface for the generators of timeout events. - // - // = DESCRIPTION - // The Event Channel can use several strategies to dispatch - // timers, for instance, it can use the ORB reactor or a pool of - // reactors running at different priorities or a pool of - // Thread_Timer_Queue_Adapters running at different priorities - // also. - // This class is the abstract base class to abstract this - // strategies. - // public: + /// destructor virtual ~TAO_EC_Timeout_Generator (void); - // destructor + /// Activate any internal threads. virtual void activate (void) = 0; - // Activate any internal threads. + /// Deactivate any internal threads, clients can destroy the object + /// after calling this method. virtual void shutdown (void) = 0; - // Deactivate any internal threads, clients can destroy the object - // after calling this method. + /// Add a timer at the given priority, returns the timer ID. virtual int schedule_timer (TAO_EC_Timeout_Filter* filter, const ACE_Time_Value& delta, const ACE_Time_Value& interval) = 0; - // Add a timer at the given priority, returns the timer ID. + /// Cancel a timer at the given priority. virtual int cancel_timer (const TAO_EC_QOS_Info& info, int id) = 0; - // Cancel a timer at the given priority. }; // **************************************************************** +/** + * @class TAO_EC_Timeout_Adapter + * + * @brief Adapt the EC_Filter interface as an Event_Handler. + * + * ACE timer queues (including the reactor) use Event_Handlers to + * dispatch events, but we want to receive them in EC_Filters, + * this class is and adaptor for that purpose. + */ class TAO_RTEvent_Export TAO_EC_Timeout_Adapter : public ACE_Event_Handler { - // = TITLE - // Adapt the EC_Filter interface as an Event_Handler. - // - // = DESCRIPTION - // ACE timer queues (including the reactor) use Event_Handlers to - // dispatch events, but we want to receive them in EC_Filters, - // this class is and adaptor for that purpose. - // public: + /// Default construction. TAO_EC_Timeout_Adapter (void); - // Default construction. private: + /// Casts <act> to EC_Filter and dispatches an event to it. virtual int handle_timeout (const ACE_Time_Value &tv, const void *act); - // Casts <act> to EC_Filter and dispatches an event to it. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Trivial_Supplier_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Trivial_Supplier_Filter.h index d84255cda4a..6fd724d12d8 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Trivial_Supplier_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Trivial_Supplier_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_trivial_Supplier_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_trivial_Supplier_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_TRIVIAL_SUPPLIER_FILTER_H #define TAO_EC_TRIVIAL_SUPPLIER_FILTER_H @@ -38,20 +28,21 @@ class TAO_EC_ProxyPushSupplier_Set; // **************************************************************** +/** + * @class TAO_EC_Trivial_Supplier_Filter + * + * @brief A null filtering strategy. + * + * This strategy does no filtering, it is useful for backends of + * the CosEventChannel, testing and broadcasters; it uses the + * ConsumerAdmin to find all the consumers and pushes the event to + * all of them. + */ class TAO_RTEvent_Export TAO_EC_Trivial_Supplier_Filter : public TAO_EC_Supplier_Filter { - // = TITLE - // A null filtering strategy. - // - // = DESCRIPTION - // This strategy does no filtering, it is useful for backends of - // the CosEventChannel, testing and broadcasters; it uses the - // ConsumerAdmin to find all the consumers and pushes the event to - // all of them. - // public: + /// Constructor TAO_EC_Trivial_Supplier_Filter (TAO_EC_Event_Channel* ec); - // Constructor // = The TAO_EC_Supplier_Filter methods. virtual void bind (TAO_EC_ProxyPushConsumer* consumer); @@ -69,26 +60,26 @@ public: virtual CORBA::ULong _incr_refcnt (void); private: + /// The event channel, used to locate the set of consumers. TAO_EC_Event_Channel *event_channel_; - // The event channel, used to locate the set of consumers. }; // **************************************************************** +/** + * @class TAO_EC_Trivial_Supplier_Filter_Builder + * + * @brief Create a single Trivial_Supplier_Filter. + * + * This Factory creates a single Trivial_Supplier_Filter that is + * used by all the suppliers (i.e. ProxyConsumers) of an event + * channel. + */ class TAO_RTEvent_Export TAO_EC_Trivial_Supplier_Filter_Builder : public TAO_EC_Supplier_Filter_Builder { - // = TITLE - // Create a single Trivial_Supplier_Filter. - // - // = DESCRIPTION - // This Factory creates a single Trivial_Supplier_Filter that is - // used by all the suppliers (i.e. ProxyConsumers) of an event - // channel. - // - // public: + /// constructor.... TAO_EC_Trivial_Supplier_Filter_Builder (TAO_EC_Event_Channel* ec); - // constructor.... // = The TAO_EC_Supplier_Filter_Builder methods... virtual TAO_EC_Supplier_Filter* @@ -97,8 +88,8 @@ public: destroy (TAO_EC_Supplier_Filter *filter); private: + /// The filter.... TAO_EC_Trivial_Supplier_Filter filter_; - // The filter.... }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_Type_Filter.h b/TAO/orbsvcs/orbsvcs/Event/EC_Type_Filter.h index 9941e5627ba..d5a1ef62aab 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_Type_Filter.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_Type_Filter.h @@ -1,26 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// ORBSVCS Real-time Event Channel -// -// = FILENAME -// EC_Type_Filter -// -// = AUTHOR -// Carlos O'Ryan (coryan@cs.wustl.edu) -// -// = CREDITS -// Based on previous work by Tim Harrison (harrison@cs.wustl.edu) -// and other members of the DOC group. -// More details can be found in: -// http://www.cs.wustl.edu/~schmidt/oopsla.ps.gz -// http://www.cs.wustl.edu/~schmidt/JSAC-98.ps.gz -// -// -// ============================================================================ +/** + * @file EC_Type_Filter.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_TYPE_FILTER_H #define TAO_EC_TYPE_FILTER_H @@ -33,18 +23,19 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_EC_Type_Filter + * + * @brief A filter based on event type/source + * + * This filter only accept events with a predefined type/source, + * both the source and the type can be wildcards. + */ class TAO_RTEvent_Export TAO_EC_Type_Filter : public TAO_EC_Filter { - // = TITLE - // A filter based on event type/source - // - // = DESCRIPTION - // This filter only accept events with a predefined type/source, - // both the source and the type can be wildcards. - // public: + /// Constructor. TAO_EC_Type_Filter (const RtecEventComm::EventHeader& header); - // Constructor. // = The TAO_EC_Filter methods, please check the documentation in // TAO_EC_Filter. @@ -74,8 +65,8 @@ private: (const TAO_EC_Type_Filter&)) private: + /// Encapsulate the type/source that we must match. RtecEventComm::EventHeader header_; - // Encapsulate the type/source that we must match. }; #if defined (__ACE_INLINE__) diff --git a/TAO/orbsvcs/orbsvcs/Event/EC_UDP_Admin.h b/TAO/orbsvcs/orbsvcs/Event/EC_UDP_Admin.h index e41cad55ead..8cddee5b51b 100644 --- a/TAO/orbsvcs/orbsvcs/Event/EC_UDP_Admin.h +++ b/TAO/orbsvcs/orbsvcs/Event/EC_UDP_Admin.h @@ -1,35 +1,16 @@ /* -*- C++ -*- */ -// $Id$ -// -// ============================================================================ -// -// = LIBRARY -// TAO services -// -// = FILENAME -// EC_UDP_Admin -// -// = AUTHOR -// Carlos O'Ryan -// -// = DESCRIPTION -// Simple implementations of the UDP Administration service. -// -// connects to a "remote" EC as a consumer, it also connects to the -// <local> EC as a supplier of events, this later EC is usually -// collocated. -// The QoS parameters for both connections must be provided by the -// user. -// To avoid infinite loops of events the Gateway descreases the TTL -// field of the events and will not deliver any events with TTL less -// than or equal to 0. -// -// = TODO -// The class makes an extra copy of the events, we need to -// investigate if closer collaboration with its collocated EC could -// be used to remove that copy. -// -// ============================================================================ +/** + * @file EC_UDP_Admin.h + * + * $Id$ + * + * @author Carlos O'Ryan (coryan@cs.wustl.edu) + * + * Based on previous work by Tim Harrison (harrison@cs.wustl.edu) and + * other members of the DOC group. More details can be found in: + * + * http://doc.ece.uci.edu/~coryan/EC/index.html + */ #ifndef TAO_EC_UDP_ADMIN_H #define TAO_EC_UDP_ADMIN_H @@ -38,26 +19,27 @@ #include "orbsvcs/RtecUDPAdminS.h" #include "orbsvcs/Event/event_export.h" +/** + * @class TAO_EC_Simple_AddrServer + * + * @brief TAO Real-time Event Service; a simple UDP address server. + * + * The EC is able to use multiple multicast groups to transmit its + * data, the is given control over the mapping between the Event + * (type,source) pair and the (ipaddr,port) pair using a + * AddrServer. + * This class implements a very simple server that simply maps the + * <type> component to the <ipaddr> and uses a fixed <port>, + * provided at initialization time. + */ class TAO_RTEvent_Export TAO_EC_Simple_AddrServer : public POA_RtecUDPAdmin::AddrServer { - // = TITLE - // TAO Real-time Event Service; a simple UDP address server. - // - // = DESCRIPTION - // The EC is able to use multiple multicast groups to transmit its - // data, the is given control over the mapping between the Event - // (type,source) pair and the (ipaddr,port) pair using a - // AddrServer. - // This class implements a very simple server that simply maps the - // <type> component to the <ipaddr> and uses a fixed <port>, - // provided at initialization time. - // public: + /// Constructor TAO_EC_Simple_AddrServer (CORBA::UShort port); - // Constructor + /// Destructor virtual ~TAO_EC_Simple_AddrServer (void); - // Destructor // = The RtecUDPAdmin::AddrServer methods virtual void get_addr (const RtecEventComm::EventHeader& header, |