| // Copyright 2020 The Dawn 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 SRC_DAWN_COMMON_NSREF_H_ | |
| #define SRC_DAWN_COMMON_NSREF_H_ | |
| #include "dawn/common/RefBase.h" | |
| #import <Foundation/NSObject.h> | |
| #if !defined(__OBJC__) | |
| # error "NSRef can only be used in Objective C/C++ code." | |
| #endif | |
| // This file contains smart pointers that automatically reference and release Objective C objects | |
| // and prototocals in a manner very similar to Ref<>. Note that NSRef<> and NSPRef's constructor add | |
| // a reference to the object by default, so the pattern to get a reference for a newly created | |
| // NSObject is the following: | |
| // | |
| // NSRef<NSFoo> foo = AcquireNSRef([NSFoo alloc]); | |
| // | |
| // NSRef overloads -> and * but these operators don't work extremely well with Objective C's | |
| // features. For example automatic dereferencing when doing the following doesn't work: | |
| // | |
| // NSFoo* foo; | |
| // foo.member = 1; | |
| // someVar = foo.member; | |
| // | |
| // Instead use the message passing syntax: | |
| // | |
| // NSRef<NSFoo> foo; | |
| // [*foo setMember: 1]; | |
| // someVar = [*foo member]; | |
| // | |
| // Also did you notive the extra '*' in the example above? That's because Objective C's message | |
| // passing doesn't automatically call a C++ operator to dereference smart pointers (like -> does) so | |
| // we have to dereference manually using '*'. In some cases the extra * or message passing syntax | |
| // can get a bit annoying so instead a local "naked" pointer can be borrowed from the NSRef. This | |
| // would change the syntax overload in the following: | |
| // | |
| // NSRef<NSFoo> foo; | |
| // [*foo setA:1]; | |
| // [*foo setB:2]; | |
| // [*foo setC:3]; | |
| // | |
| // Into (note access to members of ObjC classes referenced via pointer is done with . and not ->): | |
| // | |
| // NSRef<NSFoo> fooRef; | |
| // NSFoo* foo = fooRef.Get(); | |
| // foo.a = 1; | |
| // foo.b = 2; | |
| // boo.c = 3; | |
| // | |
| // Which can be subjectively easier to read. | |
| template <typename T> | |
| struct NSRefTraits { | |
| static constexpr T kNullValue = nullptr; | |
| static void Reference(T value) { | |
| [value retain]; | |
| } | |
| static void Release(T value) { | |
| [value release]; | |
| } | |
| }; | |
| template <typename T> | |
| class NSRef : public RefBase<T*, NSRefTraits<T*>> { | |
| public: | |
| using RefBase<T*, NSRefTraits<T*>>::RefBase; | |
| const T* operator*() const { | |
| return this->Get(); | |
| } | |
| T* operator*() { | |
| return this->Get(); | |
| } | |
| }; | |
| template <typename T> | |
| NSRef<T> AcquireNSRef(T* pointee) { | |
| NSRef<T> ref; | |
| ref.Acquire(pointee); | |
| return ref; | |
| } | |
| // This is a RefBase<> for an Objective C protocol (hence the P). Objective C protocols must always | |
| // be referenced with id<ProtocolName> and not just ProtocolName* so they cannot use NSRef<> | |
| // itself. That's what the P in NSPRef stands for: Protocol. | |
| template <typename T> | |
| class NSPRef : public RefBase<T, NSRefTraits<T>> { | |
| public: | |
| using RefBase<T, NSRefTraits<T>>::RefBase; | |
| const T operator*() const { | |
| return this->Get(); | |
| } | |
| T operator*() { | |
| return this->Get(); | |
| } | |
| }; | |
| template <typename T> | |
| NSPRef<T> AcquireNSPRef(T pointee) { | |
| NSPRef<T> ref; | |
| ref.Acquire(pointee); | |
| return ref; | |
| } | |
| #endif // SRC_DAWN_COMMON_NSREF_H_ |