Realm

Realm 使用的Schema 。

用于创建Realm实例的Configuration值。

指示 Realm 是否包含任何对象。

获取默认 Realm 的实例。

默认 Realm 在 iOS 上作为default.realm保留在应用程序的文档目录中，在 OS X 上则保留在应用程序的Application 支持目录中。

默认 Realm 是使用默认Configuration创建的，可以通过将Realm.Configuration.defaultConfiguration属性设置为新值来更改该默认值。

获取具有给定配置的Realm实例。

获取在指定文件 URL 持久保存的Realm实例。

异步打开 Realm 并将其传递到给定队列上的区块。

异步打开 Realm 会在分派到给定队列之前，在背景线程上执行使 Realm 进入可用状态（例如运行可能耗时的迁移）所需的所有工作。此外，同步 Realm 会等待操作开始下载并在本地可用时所有可用的远程内容。

传递给回调函数的 Realm 被限制在回调队列中，就像使用了Realm(configuration:queue:)一样。

一个任务对象，可用于观察或取消异步打开。

当异步打开同步 Realm 时，会在调用完成回调之前从服务器下载 Realm 的最新状态。 此任务对象可用于观察下载状态或取消下载。 应该使用此方法，而不是尝试通过同步会话观察下载，因为同步会话本身是异步创建的，并且当 Realm.asyncOpen() 返回时可能还不存在。

在写事务（write transaction）中执行给定区块中包含的操作。

如果区块抛出错误，则事务将被取消，并且在错误发生之前所做的任何更改都将被回滚。

每个 Realm 文件一次只能打开一个写事务（write transaction）。写事务（write transaction）不能嵌套，尝试在已处于写事务（write transaction）中的 Realm 上开始写事务（write transaction）会引发异常。writeRealm从其他线程或其他进程中同一 Realm 文件的实例调用 会受到阻塞，直到当前写事务（write transaction）完成或取消。

在开始写事务（write transaction）之前， write会将Realm实例更新到最新的 Realm 版本，就好像已调用refresh()一样，并生成通知（如适用）。如果 Realm 已经是最新的，则此操作无效。

您可以通过传入特定通知块的关联通知令牌来跳过通知特定通知块有关此写事务（write transaction）中所做更改的操作。当写事务（write transaction）正在保存用户界面中已进行的更改并且您不希望让通知块尝试重新应用相同的更改时，这主要有用。

传递给此函数的令牌必须用于此 Realm 的通知，这些通知是在执行写事务（write transaction）的同一线程上添加的。使用此方法无法跳过不同线程的通知。

在 Realm 上开始写事务。

每个 Realm 文件一次只能打开一个写事务（write transaction）。写事务（write transaction）不能嵌套，尝试在已处于写事务（write transaction）中的 Realm 上开始写事务（write transaction）会引发异常。beginWriteRealm从其他线程或其他进程中同一 Realm 文件的实例调用 会受到阻塞，直到当前写事务（write transaction）完成或取消。

在开始写事务（write transaction）之前， beginWrite会将Realm实例更新到最新的 Realm 版本，就好像已调用refresh()一样，并生成通知（如适用）。如果 Realm 已经是最新的，则此操作无效。

让写事务（write transaction）跨越事件循环的多个周期很少是一个好主意，但如果您确实希望这样做，则需要确保参与写事务（write transaction）的 Realm 保持活动状态，直到提交写事务（write transaction）。

提交当前写事务（write transaction）中的所有写操作，并结束事务。

保存更改并完成写事务（writeRealm transaction）后，将同步调用在此特定实例上注册的所有通知块。其他线程上的Realm实例的通知块以及为任何 Realm collection（包括当前线程上的collection）注册的块都会安排同步调用。

您可以通过传入特定通知块的关联通知令牌来跳过通知特定通知块有关此写事务（write transaction）中所做更改的操作。当写事务（write transaction）正在保存用户界面中已进行的更改并且您不希望让通知块尝试重新应用相同的更改时，这主要有用。

传递给此函数的令牌必须用于此 Realm 的通知，这些通知是在执行写事务（write transaction）的同一线程上添加的。使用此方法无法跳过不同线程的通知。

恢复当前写事务（write transaction）中进行的所有写入并结束事务。

这会将 Realm 中的所有对象回滚到写事务（write transaction）开始时的状态，然后结束事务。

这会恢复已删除对象的数据，但不会恢复失效的对象实例。 任何添加到 Realm 中的Object都将失效，而不是变为非托管状态。

给定以下代码：

let oldObject = objects(ObjectType).first!
let newObject = ObjectType()

realm.beginWrite()
realm.add(newObject)
realm.delete(oldObject)
realm.cancelWrite()

oldObject和newObject都会为isInvalidated返回true ，但重新运行提供oldObject的查询将再次返回有效对象。

在事务期间修改的任何对象上的 KVO 观察者都会收到关于更改回其初始值的通知，但取消的写事务（write transaction）不会生成其他通知。

无论写事务（write transaction）如何启动，该函数都适用。值得注意的是，可以从传递给write或writeAsync的区块内部调用它。

指示 Realm 当前是否处于写事务（write transaction）中。

异步执行写事务（write transaction）中给定区块中包含的操作。写事务（write transaction）以异步方式开始，就像调用beginAsyncWrite一样，默认情况下，事务在区块完成后异步提交。您还可以在区块中显式调用commitWrite或cancelWrite来同步提交或取消写事务（write transaction）。在没有这些调用的情况下返回相当于调用commitWrite 。

@param block 包含要执行的操作的区块。

@param completedBlock 一旦提交完成或因错误而失败，将在源线程或队列上调用的块。

@return 标识异步事务的 ID，可在调用区块之前将其传递给cancelAsyncWrite ，以取消区块的待处理调用。

开始异步写事务（write transaction）。此函数在背景线程上异步开始写事务（write transaction），然后在事务开始后调用原始线程或队列上的区块。与beginWrite不同，如果另一个线程当前处于写事务（write transaction）中，则这不会阻塞调用线程，并且始终会立即返回。多次调用此函数（或执行异步写事务（write transaction）的其他函数）会将要调用的区块按照排队的顺序进行排队。这包括来自写事务（write transaction）内部的调用，与同步事务不同，这种调用是允许的。

@param asyncWriteBlock 包含要在写事务（write transaction）中执行的操作的区块。asyncWriteBlock应以调用commitAsyncWrite或commitWrite结束。 在没有这些调用的情况下返回相当于调用cancelAsyncWrite 。

@return 标识异步事务的 ID，可在调用区块之前将其传递给cancelAsyncWrite ，以取消区块的待处理调用。

异步提交写事务（write transaction）。调用立即返回，允许调用者继续操作，同时在专用背景线程上执行 I/O。无论写事务（write transaction）是使用beginWrite还是beginAsyncWrite开始，都可以使用此选项。

@param onComplete 一旦提交完成或因错误而失败，将在源线程或队列上调用的区块。

@param allowGrouping 如果为true ，则对commitAsyncWrite的多个顺序调用可以一起批处理，并在一个群组中持久保存到稳定存储中。 这提高了写入性能，尤其是当批处理的单个事务很小时。 在事件发生崩溃或电源故障的情况下，所有的事务都将丢失，或者没有，而不是通常保证在提交调用返回后立即持久保存数据。

@return 在调用完成区块之前，可以将标识异步事务提交的 ID 传递给cancelAsyncWrite ，以取消该区块的待处理调用。 请注意，这不会取消提交本身。

取消异步事务的排队区块。 这可以取消传递给异步开始或异步提交的区块。 取消开始会完全取消该事务，而取消提交只是取消对完成回调的调用，提交仍然会发生。 事务只能在调用区块之前取消，并且从区块内调用cancelAsyncWrite属于不操作操作。

@param AsyncTransactionId 来自beginAsyncWrite或commitAsyncWrite的事务 ID。

指示 Realm 当前是否正在执行异步写入操作。 在调用beginAsyncWrite 、 commitAsyncWrite或writeAsync后，它将变为true ，并保持这种状态直到所有计划的异步写入工作完成。

如果在 Realm 中添加或创建的对象具有已存在的主键，该怎么办？

向此 Realm 添加一个非托管对象。

如果此 Realm 中已存在具有相同主键的对象，则会使用所选UpdatePolicy指定的此对象的属性值来更新该对象。 对于没有主键的对象，更新策略必须为.error 。

向 Realm 添加对象时，也会添加该对象引用的所有子关系（通过Object和List<Object>属性）。 这些对象也必须是有效对象才能添加到此 Realm，并且update:参数的值会传播到这些添加。

要添加的对象必须是非托管对象或已受此 Realm 托管的有效对象。 添加已由此 Realm 托管的对象属于无需操作，而添加由另一个 Realm 托管或已从任何 Realm 中删除的对象（即isInvalidated为true的对象）则为错误操作。

要将托管对象从一个 Realm 复制到另一个 Realm，请改用create() 。

将collection中的所有对象添加到 Realm 中。

创建具有给定值的 Realm 对象，将其添加到 Realm 中并返回。

value参数可以是 Realm 对象、键值编码兼容对象、从NSJSONSerialization中的方法返回的数组或字典，或者是包含每个托管属性一个元素的Array 。 请勿传入LinkingObjects实例，无论是单独传入还是作为collection成员传入。如果value参数是数组，则所有属性都必须存在、有效，并且顺序与模型中定义的属性相同。

如果 Realm 对象类型 没有主键，或者不存在具有指定主键的对象，则会在 Realm 中创建一个新对象。如果 Realm 中已存在具有指定主键的对象，并且更新策略为.modified或.all ，则现有对象将被更新，并返回对该对象的引用。

如果正在更新对象，则其模式中定义的所有属性都将通过使用键值编码从value复制来设置。 如果value参数不响应给定属性名称（或 getter 名称，如果已定义）的value(forKey:) ，则该值将保持不变。 通过使用NSNull作为更新值，或者（如果要传入Object子类的实例）将value的相应属性设置为 nil，可以将对象上的可空属性设置为 nil。

从 Realm 中删除对象。 对象一旦被删除，即被视为失效。

从 Realm 中删除零个或多个对象。

请勿将切片传递给Results或任何其他自动updating Realm collection类型（例如，Swift suffix(_:)标准库方法返回的类型）。相反，使用Array()复制要删除的对象，然后将其传递。 直接将视图传递到自动collection中可能会导致引发“索引越界”异常。

从 Realm 中删除所有对象。

返回存储在 Realm 中的给定类型的所有对象。

从 Realm 中检索具有给定主键的给定对象类型的单个实例。

此方法要求覆盖给定对象类的primaryKey() 。

为对此 Realm 所做的变更添加通知处理程序，并返回通知令牌。

通知处理程序在提交每个写事务（write transaction）后调用，与线程或进程无关。

在添加处理程序块的同一线程上调用处理程序块，并且只能在当前位于事件循环内的线程上添加处理程序块。除非您专门在背景线程上创建并运行事件循环，否则这通常只是主线程。

只要事件循环被其他活动阻止，就无法传递通知。当无法立即发送通知时，可以合并多个通知。

只要您希望将更新发送到区块，就必须保留返回的令牌。 要停止接收更新，请对令牌调用invalidate() 。

将此属性设置为true ，以便在其他线程中发生更改时自动更新此 Realm。

如果设置为true （默认），则在其他线程上所做的更改将在提交更改后的下一个事件循环周期反映在此 Realm 中。如果设置为false ，则必须手动对 Realm 调用refresh()来进行更新，从而获取最新数据。

请注意，背景情况下，事件循环没有活动的事件循环，即使将autorefresh设置为true ，您也需要手动调用refresh()才能更新到最新版本。

即使启用了此属性，您仍然可以随时调用refresh()以在自动刷新之前更新 Realm。

无论是否启用自动刷新，在提交写事务（write transaction）时都会发送通知。

在没有任何强引用的Realm上禁用autorefresh不会产生任何影响，并且autorefresh将在下次创建 Realm 时恢复为true 。 这通常无关紧要，因为它意味着无需刷新任何内容（因为托管Object List、Results 和Realm 对管理它们的 有强引用），但这意味着设置autorefresh = false application(_:didFinishLaunchingWithOptions:)稍后才存储 Realm 对象将不起作用。

默认值为 true。

更新 Realm 和由 Realm 托管的未完成对象，使其点向最新数据并提供所有适用的通知。

默认情况下，Realm 会以比此功能更有效的方式自动刷新。 应尽可能避免使用此函数。

如果此 Realm 被冻结，则返回。

返回此 Realm 的冻结（不可变）快照。

冻结 Realm 是特定版本 Realm 数据的不可变快照视图。 与普通 Realm 实例不同，它不会实时更新以反映对 Realm 进行的写入，并且可以从任何线程进行访问。 写入冻结的 Realm 是不被允许的，尝试开始写事务（write transaction）会引发异常。

从冻结 Realm 读取的所有对象和collection也将被冻结。

返回此 Realm 的实时（可变）引用。

从返回的 Realm 引用中读取的所有对象和collection将不再被冻结。如果在尚未冻结的 Realm 上调用，将返回 self。

返回给定对象的冻结（不可变）快照。

冻结副本是一个不可变对象，其中包含与给定对象当前包含的数据相同的数据，但在写入包含的 Realm 时不会更新。 与活动对象不同，冻结对象可以从任何线程访问。

返回此对象的实时（可变）引用。

此方法为同一冻结对象的实时副本创建托管访问器。 如果在已经存在的对象上调用，则会返回 self。

返回给定collection的冻结（不可变）快照。

冻结副本是一个不可变的collection，其中包含与给定collection当前包含的数据相同的数据，但在写入包含的 Realm 时不会更新。与实时集合不同，冻结集合可以从任何线程访问。

使 Realm 托管的所有Object 、 Results 、 LinkingObjects和List失效。

Realm 对其访问的数据版本持有读锁（read lock），因此在不同线程上对该 Realm 所做的更改不会修改或删除该 Realm 看到的数据。调用此方法会释放读锁（read lock），从而允许以后的写事务（write transaction）重用磁盘上使用的空间，而不是增加文件。在您之前从 Realm 读取不再需要的数据的背景线程上执行长时间阻塞操作之前，应先调用此方法。

当前线程上从此Realm实例获取的所有Object 、 Results和List实例都会失效。 不能使用Object和Array 。 Results将变空。 Realm 本身仍然有效，并且下次从 Realm 读取数据时会隐式开始新的读取事务。

在没有从 Realm 读取任何数据的情况下，或者在从 Realm 读取任何数据之前，连续多次调用此方法是不执行任何操作的。

将压缩且可选加密的 Realm 副本写入给定的本地 URL。

目标文件不能是已经存在的文件。

请注意，如果从写事务（write transaction）中调用此方法，则写入当前数据，而不是提交上一个写事务（write transaction）时的点的数据。

将 Realm 副本写入给定配置指定的给定位置。

如果提供的配置派生自User ，则将在启用同步功能的情况下复制此 Realm。

目标文件不能是已经存在的文件。

检查给定配置的 Realm 文件是否存在于磁盘本地。

对于非同步、非内存中的 Realm，这相当于FileManager.default.fileExists(atPath:) 。 对于同步 Realm，它负责根据服务器、虚拟路径和用户计算磁盘上的实际路径，就像打开 Realm 时所做的那样。

@param config 要检查是否存在的 Realm 配置。 @return 如果磁盘上存在给定配置的 Realm 文件，则返回 true，否则返回 false。

删除给定配置的本地 Realm 文件和关联的临时文件。

这会删除“域”、“.note”和“. Management”文件，这些文件是通过打开具有给定配置的 Realm 创建的。它不会删除锁文件（该文件不包含持久数据，并且每次打开 Realm 文件时都会从头开始重新创建）。

Realm 当前不得在任何线程或其他进程中打开。 如果是，则会引发 .alreadyOpen 错误。 在删除操作发生时，尝试在另一个线程上打开 Realm 会被阻塞，然后再创建并打开新的 Realm。

如果 Realm 不存在，则返回false 。

@param config Realm 配置，用于标识要删除的 Realm。 @return true 如果删除了任何文件，则为 false。

每次对象更改时发出 Void 的发布者。

尽管有这个名称，但它实际上是在collection发生更改后发出的。

描述 Realm 错误域中的错误代码的结构体。 这些值可用于捕获各种可恢复的错误，尤其是在初始化 Realm 实例时发生的错误。

let realm: Realm?
do {
    realm = try Realm()
} catch Realm.Error.incompatibleLockFile {
    print("Realm Browser app may be attached to Realm on device?")
}

在给定路径上的 Realm 上执行给定 Realm 配置的迁移区块。

首次打开 Realm 时会自动调用此方法，无需显式调用。 您可以选择调用此方法来精确控制执行迁移的时间和方式。

返回两个Realm实例是否相等。

指示对 Realm 进行更改的通知。

获取具有给定配置的Realm实例，可能是异步获取。 默认情况下，这只是返回 Realm 实例，就像使用同步初始化一样。它可以选择异步打开 Realm，在背景线程上执行将 Realm 变为可用状态所需的所有工作。对于本地 Realm，这意味着迁移将在背景运行，而对于同步 Realm，所有数据都将在返回 Realm 之前从服务器下载。

异步获取与给定 Actor 隔离的Realm实例。

打开带有 actor 的 Realm 会将 Realm 与该 actor 隔离。 Realm 不能被限制在打开 Realm 的特定线程中，而是只能在该 actor 或与该 actor 隔离的函数内部使用。 将 Realm 与 actor 隔离后，还可以使用asyncWrite和asyncRefresh 。

为 Realm 工作做好准备的所有初始化工作（例如创建、迁移或压缩磁盘上的文件，以及等待同步的 Realm 从服务器下载最新数据）都是在背景线程上完成的，并且不会阻塞调用执行程序。

使用 actor 隔离的 Realm 时，强烈建议启用结构体并发检查（Xcode 中的SWIFT_STRICT_CONCURRENCY=complete ）和运行时数据争用检测（通过将-Xfrontend -enable-actor-data-race-checks传递给编译器）。

异步获取与当前 Actor 隔离的Realm实例。

打开带有 actor 的 Realm 会将 Realm 与该 actor 隔离。 Realm 不能被限制在打开 Realm 的特定线程中，而是只能在该 actor 或与该 actor 隔离的函数内部使用。 将 Realm 与 actor 隔离后，还可以使用asyncWrite和asyncRefresh 。

为 Realm 工作做好准备的所有初始化工作（例如创建、迁移或压缩磁盘上的文件，以及等待同步的 Realm 从服务器下载最新数据）都是在背景线程上完成的，并且不会阻塞调用执行程序。

在写事务（write transaction）中执行给定区块中包含的操作。

此函数与同步write的不同之处在于，它在等待轮到写入时会挂起调用任务，而不是阻塞线程。 此外，将数据写入磁盘的实际 I/O 由背景工作线程完成。对于小型写入，与手动将写入分派到背景线程相比，在主线程上使用此函数阻塞主线程的时间可能更短。

如果区块抛出错误，则事务将被取消，并且在错误发生之前所做的任何更改都将被回滚。

每个 Realm 文件一次只能打开一个写事务（write transaction）。写事务（write transaction）不能嵌套，尝试在已处于写事务（write transaction）中的 Realm 上开始写事务（write transaction）会引发异常。writeRealm从其他线程或其他进程中同一 Realm 文件的实例调用 会受到阻塞，直到当前写事务（write transaction）完成或取消。

在开始写事务（write transaction）之前， asyncWrite会将Realm实例更新到最新的 Realm 版本，就好像已调用asyncRefresh()一样，并生成通知（如适用）。如果 Realm 已经是最新的，则此操作无效。

您可以通过传入特定通知块的关联通知令牌来跳过通知特定通知块有关此写事务（write transaction）中所做更改的操作。当写事务（write transaction）正在保存用户界面中已进行的更改并且您不希望让通知块尝试重新应用相同的更改时，这主要有用。

传递给此函数的令牌必须用于此 Realm 的通知，这些通知被添加到与执行写事务（write transaction）相同的 actor 上。使用此方法无法跳过不同线程的通知。

更新 Realm 和由 Realm 托管的未完成对象，使其点向最新数据并提供所有适用的通知。

应使用此函数而不是异步函数中的同步refresh ，因为它会暂停调用任务（如果需要）而不是阻塞。

在写事务（write transaction）中执行给定区块中包含的操作。

此函数与同步write的不同之处在于，它在等待轮到写入时会挂起调用任务，而不是阻塞线程。 此外，将数据写入磁盘的实际 I/O 由背景工作线程完成。对于小型写入，与手动将写入分派到背景线程相比，在主线程上使用此函数阻塞主线程的时间可能更短。

如果区块抛出错误，则事务将被取消，并且在错误发生之前所做的任何更改都将被回滚。

每个 Realm 文件一次只能打开一个写事务（write transaction）。写事务（write transaction）不能嵌套，尝试在已处于写事务（write transaction）中的 Realm 上开始写事务（write transaction）会引发异常。writeRealm从其他线程或其他进程中同一 Realm 文件的实例调用 会受到阻塞，直到当前写事务（write transaction）完成或取消。

在开始写事务（write transaction）之前， asyncWrite会将Realm实例更新到最新的 Realm 版本，就好像已调用asyncRefresh()一样，并生成通知（如适用）。如果 Realm 已经是最新的，则此操作无效。

您可以通过传入特定通知块的关联通知令牌来跳过通知特定通知块有关此写事务（write transaction）中所做更改的操作。当写事务（write transaction）正在保存用户界面中已进行的更改并且您不希望让通知块尝试重新应用相同的更改时，这主要有用。

传递给此函数的令牌必须用于此 Realm 的通知，这些通知被添加到与执行写事务（write transaction）相同的 actor 上。使用此方法无法跳过不同线程的通知。

更新 Realm 和由 Realm 托管的未完成对象，使其点向最新数据并提供所有适用的通知。

应使用此函数而不是异步函数中的同步refresh ，因为它会暂停调用任务（如果需要）而不是阻塞。

Configuration实例描述了用于创建 Realm 实例的不同选项。

Configuration 实例只是普通的 Swift 结构体。 与Realm和Object不同，只要不改变它们，就可以在线程之间自由共享。

为类子集创建配置值（通过设置objectClasses属性）的成本可能很高。 因此，您通常希望为每个不同的配置缓存并重复使用单个配置值，而不是在每次打开 Realm 时都创建一个新值。

返回与首次创建ThreadSafeReference时引用的对象相同的对象，但已解析为该线程的当前 Realm。 如果在创建引用后删除了该对象，则返回nil 。