BLBackgroundRealm

BLBackgroundRealm is a collection of handy classes and extensions that make it easier to work with RLMRealm in the background.

It's main focus is to enhance existing RLMRealms and Realm-based code bases with very little overhead and refactoring.

Note: Although this module makes it more convenient to work with a RLMRealm in the background, it does not make RLMRealms nor its objects thread-safe. They should still be accessed only from within their appropriate thread.

Specs

• Realm 3.0.0+
• iOS 9+
• tvOS 10+
• watchOS 3+
• macOS 10.10+

Swift

For the Swift counterpart, see BackgroundRealm.

Writing to a Realm in the background

Commiting write transactions in the background becomes as easy as:

[RLMRealm writeInBackgroundWithConfiguration:<#(nonnull RLMRealmConfiguration *)#>
                                    andBlock:^(RLMRealm * _Nullable realm, BLBackgroundRealmError * _Nullable error) 
{
    <#code#>
}];

Optionally, you can set a default backgroundConfiguration that will be used in all write transactions in the background:

RLMRealmConfiguration *config = [[RLMRealmConfiguration alloc] init];
config.fileURL = url;
[RLMRealmConfiguration setBackgroundConfiguration:config];

[RLMRealm writeInBackgroundWithBlock:^(RLMRealm * _Nullable realm, BLBackgroundRealmError * _Nullable error) {
    <#code#>
}];

Finally, you can easily move from any Realm instance to its background counterpart:

RLMRealm *realm = [RLMRealm defaultRealm];

[realm writeInBackgroundWithBlock:^(RLMRealm * _Nullable realm, BLBackgroundRealmError * _Nullable error) {
    <#code#>
}];

The BackgroundRealm

Background Realm exposes a BLBackgroundRealm class, which basically:

1. creates a private NSThread and NSRunLoop where a new background RLMRealm will be opened
2. opens a RLMRealm in the private thread
3. runs work in the background thread

This is particularly useful if you'd like to:

• make computationally expensive changes to the RLMRealm
• register for change notifications in the background, without necessarily triggering a UI update right away

Usage

• Creating a BLBackgroundRealm using [RLMConfiguration backgroundConfiguration]:

BLBackgroundRealm *bgRealm = [BLBackgroundRealm backgroundRealmWithBlock:^(RLMRealm * _Nullable realm, BLBackgroundRealmError * _Nullable error) {
    <#code#>
}];

• Creating a BLBackgroundRealm using a custom configuration:

[BLBackgroundRealm backgroundRealmWithConfiguration:<#(nonnull RLMRealmConfiguration *)#> 
                                           andBlock:^(RLMRealm * _Nullable realm, BLBackgroundRealmError * _Nullable error) 
{
    <#code#>
}];

• Creating a BLBackgroundRealm using a file NSURL:

[BLBackgroundRealm backgroundRealmWithFileURL:<#(nonnull NSURL *)#> 
                                     andBlock:^(RLMRealm * _Nullable realm, BLBackgroundRealmError * _Nullable error) 
{
    <#code#>
}];

Installation

Cocoapods

pod 'BLBackgroundRealm', '~> 1.0'

Then #import <BLBackgroundRealm/BLBackgroundRealm.h> where needed.

Carthage

github "BellAppLab/BLBackgroundRealm" ~> 1.0

Then #import <BLBackgroundRealm/BLBackgroundRealm.h> where needed.

Git Submodules

cd toYourProjectsFolder
git submodule add -b submodule --name BLBackgroundRealm https://github.com/BellAppLab/BLBackgroundRealm.git

Then drag the BLBackgroundRealm folder into your Xcode project.

Forks

When forking this repo, make sure to download the Realm framework and add it manually to the project.

• Realm - Objective-C - v3.0.0
• Realm - Objective-C - latest

Author

Bell App Lab, [email protected]

Contributing

Check this out.

Credits

Logo image by mikicon from The Noun Project

License

BackgroundRealm is available under the MIT license. See the LICENSE file for more info.