CF_RETURNS_RETAINED 或 CF_RETURNS_NOT_RETAINED：什么时候使用？

Question

我不确定是使用 CF_RETURNS_RETAINED 还是 CF_RETURNS_NOT_RETAINED 来返回 CFDataProviderRef 的自定义函数。

根据the documentation at the location where the macros are defined，两者都应该只在特殊情况下使用，正确的修复应该是修复我的命名约定。 但是 swift/objective-c 文档 suggests using 他们注释任何返回 CoreFoundation 指针的函数，而没有真正解释何时使用哪个 --- 如果我不注释它们，我需要每次在 swift 中手动指定行为代码。

我可以找到的更多文档解释了如何使用 ARC 值 +1 和另一个 0，但恐怕这对我的理解没有多大帮助。

我的问题：

1. 我应该使用它们，还是按照Base.h 的建议改进我的命名？
2. 那里使用的确切命名约定是什么？
3. 我是否正确假设如果我希望返回的对象使用的内存在调用者超出范围后立即释放，而如果我不希望发生这种情况，我应该使用另一个（因为我在其他地方使用了指向它的指针，或者我自己清理了）？
4. 我的函数所做的只是返回一个CFDataProviderRef，这是我从对CGDataProviderCreateSequential 的调用中得到的。我想这意味着我希望行为为CGDataProviderCreateSequential（对吗？）。如何确定该函数是使用 CF_RETURNS_RETAINED 还是 CF_RETURNS_NOT_RETAINED（CGDataProvider.h 文件中没有）？

Answer 1

这一切都与所有权有关。命名约定是 Core Foundation 的命名约定，描述为 here。创建规则说，名称中带有“创建”和“复制”的函数让调用者拥有返回对象的所有权（尽管不一定是 sole 所有权）。这意味着调用者有责任最终使用CFRelease() 释放返回的对象。 Get 规则表示，创建或复制函数以外的函数不赋予调用者对象的所有权，因此调用者不得在其上调用 CFRelease()（当然，除了平衡对 CFRetain() 的任何显式调用）。

如果一个函数在语义上是一个创建或复制函数，它将所有权返回给调用者，但它的名称没有表明这一点，你应该使用CF_RETURNS_RETAINED 来表明这一点。同样，如果一个函数的名称包含“创建”或“复制”，但它没有与创建规则匹配的语义，您应该使用CF_RETURNS_NOT_RETAINED 来表明这一点。 （尽量避免这种情况。）

由于您的代码正在调用 CGDataProviderCreateSequential() 并且名称中包含“Create”，因此您的代码负责释放返回的 CGDataProvider 对象。如果您在函数中直接释放它，那么您的调用者将无法访问它。您想将对象返回给调用者。您还希望将释放对象的责任传递给调用者，因为您不知道调用者何时会完成它。因此，您应该在名称中使用“Create”来命名您的函数，以向调用者和自动化系统表明调用者负责释放对象。或者，您可以使用 CF_RETURNS_RETAINED 注释您的函数以表示这一点，但遵循命名约定更好。

Swift 可能只尊重系统头文件的命名约定。我不知道。在这种情况下，您必须使用CF_RETURNS_RETAINED 进行注释，即使您的函数名称中有“Create”。注释名称已经遵循约定的函数没有害处。它是多余但无害的。