include/GaudiKernel/IPartitionControl.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2019 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 #ifndef GAUDIKERNEL_IPARTITIONCONTROL_H
0012 #define GAUDIKERNEL_IPARTITIONCONTROL_H
0013
0014 // Framework include files
0015 #include "GaudiKernel/IInterface.h"
0016
0017 // C++ include files
0018 #include <string>
0019
0020 /**@class IPartitionControl IPartitionControl.h GaudiKernel/IPartitionControl.h
0021  *
0022  * Create / access partitions.
0023  * Partitioning is used to switch between different instances of
0024  * multi-services like it is used e.g. in the event buffer tampering.
0025  *
0026  *
0027  * Example code:
0028  * =============
0029  *
0030  * Switch between buffers for data processing.
0031  * Use this technique to populate e.g. different datastores
0032  * in order to later compare the different results.
0033  *
0034  * auto partCtrl = eventSvc().as<IPartitionControl>();
0035  * if ( partCtrl )  {
0036  *   if ( partCtrl.activate("Partition_1").isSuccess() )  {
0037  *      SmartDataPtr mcparts(eventSvc(), "MC/Particles");
0038  *      .... work with particles from buffer "Partition 1"
0039  *      all data registered by code here will go to "Partition 2"
0040  *   }
0041  *   if ( partCtrl.activate("Partition_2").isSuccess() )  {
0042  *      SmartDataPtr mcparts(eventSvc(), "MC/Particles");
0043  *      .... work with particles from buffer "Partition 2"
0044  *      they are NOT they same as those in buffer 1
0045  *      all data registered by code here will go to "Partition 2"
0046  *   }
0047  * }
0048  *
0049  * The access to the underlying service is also possible.
0050  *
0051  * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
0052  *
0053  * Be careful: This usage MAY NOT MODIFY e.g. the datastore
0054  * by adding additional objects! This should solely by
0055  * used for analysis after buffer tampering. In particular
0056  * with "data on demand" this can easily have unexpected results.
0057  *
0058  * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
0059  *
0060  * auto partCtrl = eventSvc().as<IPartitionControl>();
0061  * if ( partCtrl )  {
0062  *   IInterface* ptr = 0;
0063  *   if ( partCtrl->get("Partition 1", ptr).isSuccess() )  {
0064  *     SmartIF<IDataProviderSvc> partition(ptr);
0065  *     // Now we can work directly with this partition
0066  *     // There is no additional dispathing in the "eventSvc()".
0067  *     SmartDataPtr mcparts(partition, "MC/Particles");
0068  *     if ( mcparts )  {
0069  *     }
0070  *   }
0071  * }
0072  *
0073  *  @author  Markus Frank
0074  *  @version 1.0
0075  */
0076 class GAUDI_API IPartitionControl : virtual public IInterface {
0077 public:
0078   /// InterfaceID
0079   DeclareInterfaceID( IPartitionControl, 1, 0 );
0080
0081   /// Create a partition object. The name identifies the partition uniquely
0082   /** Create a new partition. If the partition exists already
0083    * the existing object is returned. In this event the return code is
0084    * PARTITION_EXISTS. The partition type typically contains all the
0085    * information necessary to access the corresponding service,
0086    * typically a pair "<service-type>/<service name>"
0087    *
0088    * @param  name          [IN]     Partition name
0089    * @param  type          [IN]     Partition type
0090    *
0091    * @return Status code indicating failure or success.
0092    */
0093   virtual StatusCode create( const std::string& name, const std::string& type ) = 0;
0094
0095   /// Create a partition object. The name identifies the partition uniquely
0096   /** Create a new partition. If the partition exists already
0097    * the existing object is returned. In this event the return code is
0098    * PARTITION_EXISTS. The partition type typically contains all the
0099    * information necessary to access the corresponding service,
0100    * typically a pair "<service-type>/<service name>"
0101    *
0102    * @param  name          [IN]     Partition name
0103    * @param  type          [IN]     Partition type
0104    * @param  pPartition    [OUT]    Reference to the created/existing partition
0105    *
0106    * @return Status code indicating failure or success.
0107    */
0108   virtual StatusCode create( const std::string& name, const std::string& type, IInterface*& pPartition ) = 0;
0109
0110   /// Drop a partition object. The name identifies the partition uniquely
0111   /** Remove a partition object. If the partition object does not exists,
0112    * the return code is PARTITION_NOT_PRESENT. The partition may not
0113    * be used anymore after this call.
0114    *
0115    * @param  name          [IN]     Partition name
0116    *
0117    * @return Status code indicating failure or success.
0118    */
0119   virtual StatusCode drop( const std::string& name ) = 0;
0120
0121   /// Drop a partition object. The name identifies the partition uniquely
0122   /** Remove a partition object. If the partition object does not exists,
0123    * the return code is PARTITION_NOT_PRESENT. The partition may not
0124    * be used anymore after this call.
0125    * If the interface pointer is invalid, IInterface::NO_INTERFACE
0126    * is returned.
0127    *
0128    * @param  pPartition    [IN]     Reference to existing partition
0129    *
0130    * @return Status code indicating failure or success.
0131    */
0132   virtual StatusCode drop( IInterface* pPartition ) = 0;
0133
0134   /// Activate a partition object. The name identifies the partition uniquely.
0135   /** Access an existing partition object. Preferred call.
0136    * The activation of a partition does not change the state of the
0137    * partition. It only means that any call issued to the corresponding
0138    * multi-service will be redirected to the this partition - typically
0139    * a service implementing the same interfaces as the multi-service.
0140    *
0141    * @param  name          [IN]     Partition name
0142    *
0143    * @return Status code indicating failure or success.
0144    */
0145   virtual StatusCode activate( const std::string& name ) = 0;
0146
0147   /// Activate a partition object.
0148   /** Access an existing partition object.
0149    * The activation of a partition does not change the state of the
0150    * partition. It only means that any call issued to the corresponding
0151    * multi-service will be redirected to the this partition - typically
0152    * a service implementing the same interfaces as the multi-service.
0153    *
0154    * If the interface pointer is invalid, IInterface::NO_INTERFACE
0155    * is returned.
0156    *
0157    * @param  pPartition    [IN]     Pointer to the partition.
0158    *
0159    * @return Status code indicating failure or success.
0160    */
0161   virtual StatusCode activate( IInterface* pPartition ) = 0;
0162
0163   /// Access a partition object. The name identifies the partition uniquely.
0164   /** Access an existing partition object.
0165    *
0166    * @param  name          [IN]     Partition name
0167    * @param  pPartition    [IN]     Location to store the pointer to the partition.
0168    *
0169    * @return Status code indicating failure or success.
0170    */
0171   virtual StatusCode get( const std::string& name, IInterface*& pPartition ) const = 0;
0172
0173   /// Access the active partition object.
0174   /** Access the active partition object.
0175    *
0176    * @param  name          [OUT]    Partition name
0177    * @param  pPartition    [OUT]    Location to store the pointer to the partition.
0178    *
0179    * @return Status code indicating failure or success.
0180    */
0181   virtual StatusCode activePartition( std::string& name, IInterface*& pPartition ) const = 0;
0182
0183   // Return codes:
0184   enum class Status : StatusCode::code_t { PARTITION_NOT_PRESENT = 2, PARTITION_EXISTS = 4, NO_ACTIVE_PARTITION = 6 };
0185 };
0186
0187 STATUSCODE_ENUM_DECL( IPartitionControl::Status )
0188
0189 #endif // GAUDIKERNEL_IPARTITIONCONTROL_H