cleanupEnabler.h

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_USD_SDF_CLEANUP_ENABLER_H
#define PXR_USD_SDF_CLEANUP_ENABLER_H

/// \file sdf/cleanupEnabler.h

#include "pxr/pxr.h"
#include "pxr/usd/sdf/api.h"
#include "pxr/base/tf/stacked.h"

PXR_NAMESPACE_OPEN_SCOPE

/// \class SdfCleanupEnabler
///
/// An RAII class which, when an instance is alive, enables scheduling of
/// automatic cleanup of SdfLayers.
/// 
/// Any affected specs which no longer contribute to the scene will be removed 
/// when the last SdfCleanupEnabler instance goes out of scope. Note that for 
/// this purpose, SdfPropertySpecs are removed if they have only required fields 
/// (see SdfPropertySpecs::HasOnlyRequiredFields), but only if the property spec 
/// itself was affected by an edit that left it with only required fields. This 
/// will have the effect of uninstantiating on-demand attributes. For example, 
/// if its parent prim was affected by an edit that left it otherwise inert, it 
/// will not be removed if it contains an SdfPropertySpec with only required 
/// fields, but if the property spec itself is edited leaving it with only 
/// required fields, it will be removed, potentially uninstantiating it if it's 
/// an on-demand property.
/// 
/// SdfCleanupEnablers are accessible in both C++ and Python.
/// 
/// /// SdfCleanupEnabler can be used in the following manner:
/// \code
/// {
///     SdfCleanupEnabler enabler;
///     
///     // Perform any action that might otherwise leave inert specs around, 
///     // such as removing info from properties or prims, or removing name 
///     // children. i.e:
///     primSpec->ClearInfo(SdfFieldKeys->Default);
/// 
///     // When enabler goes out of scope on the next line, primSpec will 
///     // be removed if it has been left as an empty over.
/// }
/// \endcode
///
TF_DEFINE_STACKED(SdfCleanupEnabler, false, SDF_API)
{
public:

    SDF_API SdfCleanupEnabler();

    SDF_API ~SdfCleanupEnabler();

    /// Returns whether cleanup is currently being scheduled.
    SDF_API static bool IsCleanupEnabled();
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif  // #ifndef PXR_USD_SDF_CLEANUP_ENABLER_H