src/backend/Builder.h

// Copyright 2017 The NXT Authors
//
// 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.

#ifndef BACKEND_BUILDER_H_
#define BACKEND_BUILDER_H_

#include "backend/Forward.h"
#include "backend/RefCounted.h"

#include "nxt/nxtcpp.h"

#include <string>

namespace backend {

    // This class implements behavior shared by all builders:
    //  - Tracking whether GetResult has been called already, needed by the
    //    autogenerated code to prevent operations on "consumed" builders.
    //  - The error status callback of the API. The callback is guaranteed to be
    //    called exactly once with an error, a success, or "unknown" if the
    //    builder is destroyed; also the builder callback cannot be called before
    //    either the object is destroyed or GetResult is called.
    //
    // It is possible for error to be generated before the error callback is
    // registered when a builder "set" function performance validation inline.
    // Because of this we have to store the status in the builder and defer
    // calling the callback to GetResult.

    class BuilderBase : public RefCounted {
        public:
            // Used by the auto-generated validation to prevent usage of the builder
            // after GetResult or an error.
            bool CanBeUsed() const;
            DeviceBase* GetDevice();

            // Set the status of the builder to an error.
            void HandleError(const char* message);

            // Internal API, to be used by builder and BackendProcTable only.
            // rReturns true for success cases, and calls the callback with appropriate status.
            bool HandleResult(RefCounted* result);

            // NXT API
            void SetErrorCallback(nxt::BuilderErrorCallback callback,
                                  nxt::CallbackUserdata userdata1,
                                  nxt::CallbackUserdata userdata2);

        protected:
            BuilderBase(DeviceBase* device);
            ~BuilderBase();

            DeviceBase* const device;
            bool gotStatus = false;

        private:
            void SetStatus(nxt::BuilderErrorStatus status, const char* message);

            nxt::BuilderErrorCallback callback = nullptr;
            nxt::CallbackUserdata userdata1 = 0;
            nxt::CallbackUserdata userdata2 = 0;

            nxt::BuilderErrorStatus storedStatus = nxt::BuilderErrorStatus::Success;
            std::string storedMessage;

            bool consumed = false;
    };

    // This builder base class is used to capture the calls to GetResult and make sure
    // that either:
    //  - There was an error, callback is called with an error and nullptr is returned.
    //  - There was no error, callback is called with success and a non-null T* is returned.
    template<typename T>
    class Builder : public BuilderBase {
        public:
            // NXT API
            T* GetResult();

        protected:
            using BuilderBase::BuilderBase;

        private:
            virtual T* GetResultImpl() = 0;
    };

    template<typename T>
    T* Builder<T>::GetResult() {
        T* result = GetResultImpl();
        // An object can have been returned but failed its initialization, so if an error
        // happened, return nullptr instead of result.
        if (HandleResult(result)) {
            return result;
        } else {
            return nullptr;
        }
    }

}

#endif // BACKEND_BUILDER_H_