134 lines
5.3 KiB
C++
134 lines
5.3 KiB
C++
#ifndef OMG_TDDS_PUB_SUSPENDED_PUBLICATION_HPP_
|
|
#define OMG_TDDS_PUB_SUSPENDED_PUBLICATION_HPP_
|
|
|
|
/* Copyright 2010, Object Management Group, Inc.
|
|
* Copyright 2010, PrismTech, Corp.
|
|
* Copyright 2010, Real-Time Innovations, Inc.
|
|
* All rights reserved.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#include <dds/pub/Publisher.hpp>
|
|
|
|
namespace dds
|
|
{
|
|
namespace pub
|
|
{
|
|
template <typename DELEGATE>
|
|
class TSuspendedPublication;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @brief
|
|
* Class for RAII way of suspending/resuming publication.
|
|
*
|
|
* Suspended publication indicates to the Service that the application is about
|
|
* to make multiple modifications using DataWriter objects belonging to
|
|
* the Publisher.
|
|
*
|
|
* It is a hint to the Service so it can optimize its performance by,
|
|
* e.g., holding the dissemination of the modifications and then batching
|
|
* them. It is not required that the Service use this hint in any way.
|
|
*
|
|
* When a Suspended publication is started, it must be matched by
|
|
* a corresponding call to SuspendedPublication::resume() or the destruction
|
|
* of the SuspendedPublication object (which is an implicit resume),
|
|
* indicating that the set of modifications has
|
|
* completed. If the Publisher is deleted before the resume,
|
|
* any suspended updates yet to be published will be discarded.
|
|
*
|
|
* This object suspends the publication of all DataWriter objects contained by
|
|
* the given Publisher. The data written, disposed or unregistered by a DataWriter is
|
|
* stored in the history buffer of the DataWriter and therefore, depending on its QoS
|
|
* settings, the following operations may block (see the operation descriptions for
|
|
* more information):
|
|
* - dds::pub::DataWriter.write (and its overloaded counterparts).
|
|
* - dds::pub::DataWriter.operator<< (and its overloaded counterparts).
|
|
* - dds::pub::DataWriter.unregister_instance (and its overloaded counterparts).
|
|
* - dds::pub::DataWriter.dispose_instance (and its overloaded counterparts).
|
|
*
|
|
* @see for more information: @ref DCPS_Modules_Publication "Publication"
|
|
* @see dds::pub::Publisher
|
|
*/
|
|
template <typename DELEGATE>
|
|
class dds::pub::TSuspendedPublication : public dds::core::Value<DELEGATE>
|
|
{
|
|
public:
|
|
/**
|
|
* Creating a SuspendedPublication object, which will suspend the
|
|
* dissemination of the publications by all contained DataWriter objects
|
|
* of the given Publisher.
|
|
*
|
|
* @param pub The publisher to supsend publications on.
|
|
* @throws dds::core::Error
|
|
* An internal error has occurred.
|
|
* @throws dds::core::AlreadyClosedError
|
|
* The Publisher has already been closed.
|
|
* @throws dds::core::NotEnabledError
|
|
* The Publisher has not yet been enabled.
|
|
* @throws dds::core::OutOfResourcesError
|
|
* The Data Distribution Service ran out of resources to
|
|
* complete this operation.
|
|
* @throws dds::core::NullReferenceError
|
|
* The Publisher was not properly created and references to dds::core::null.
|
|
*/
|
|
explicit TSuspendedPublication(const dds::pub::Publisher& pub);
|
|
|
|
public:
|
|
/**
|
|
* This operation will explicitly resume the publication of all
|
|
* DataWriter objects contained by the given Publisher at construction.
|
|
*
|
|
* All data held in the history
|
|
* buffer of the DataWriter's is actively published to the consumers. When the
|
|
* operation returns all DataWriter's have resumed the publication of suspended
|
|
* updates.
|
|
*
|
|
* If the Publisher already resumed its publication (by a call to this very
|
|
* operation), then a call to this operation will have no effect.
|
|
*
|
|
* @throws dds::core::Error
|
|
* An internal error has occurred.
|
|
* @throws dds::core::AlreadyClosedError
|
|
* The Publisher has already been closed.
|
|
* @throws dds::core::NotEnabledError
|
|
* The Publisher has not yet been enabled.
|
|
* @throws dds::core::OutOfResourcesError
|
|
* The Data Distribution Service ran out of resources to
|
|
* complete this operation.
|
|
* @throws dds::core::NullReferenceError
|
|
* The Publisher was not properly created and references to dds::core::null.
|
|
*/
|
|
void resume();
|
|
|
|
public:
|
|
/**
|
|
* The destruction of the SuspendedPublication will implicitly resume
|
|
* the publication if not already resumed by a call to resume().
|
|
*
|
|
* All data held in the history
|
|
* buffer of the DataWriter's is actively published to the consumers. When the
|
|
* operation returns all DataWriter's have resumed the publication of suspended
|
|
* updates.
|
|
*
|
|
* When there is a problem with which resume() would normally throw an exception,
|
|
* then that exception is swallowed. Errors can be found in the logs.
|
|
*/
|
|
~TSuspendedPublication();
|
|
};
|
|
|
|
|
|
#endif /* OMG_TDDS_PUB_SUSPENDED_PUBLICATION_HPP_ */
|