Properties

autorefresh

Set to YES to automatically update this Realm when changes happen in other threads.

@property (nonatomic) BOOL autorefresh

Discussion

If set to YES (the default), changes made on other threads will be reflected
in this Realm on the next cycle of the run loop after the changes are
committed. If set to NO, you must manually call refresh on the Realm to
update it to get the latest version.

Even with this enabled, you can still call refresh at any time to update the
Realm before the automatic refresh would occur.

Notifications are sent when a write transaction is committed whether or not
this is enabled.

Disabling this on an RLMRealm without any strong references to it will not
have any effect, and it will switch back to YES the next time the RLMRealm
object is created. This is normally irrelevant as it means that there is
nothing to refresh (as persisted RLMObjects, RLMArrays, and RLMResults have strong
references to the containing RLMRealm), but it means that setting
RLMRealm.defaultRealm.autorefresh = NO in
application:didFinishLaunchingWithOptions: and only later storing Realm
objects will not work.

Declared In

schema

Declared In

RLMRealm.h

Class Methods

defaultRealm

Obtains an instance of the default Realm.

+ (instancetype)defaultRealm

Return Value

The default RLMRealm instance for the current thread.

Discussion

The default Realm is used by the RLMObject class methods
which do not take a RLMRealm parameter, but is otherwise not special. The
default Realm is persisted as default.realm under the Documents directory of
your Application on iOS, and in your application’s Application Support
directory on OS X.

RLMRealm objects are cached internally by Realm, and calling this method
multiple times on a single thread within a single iteration of the run loop
will normally return the same RLMRealm object. If you specifically want to
ensure a RLMRealm object is destroyed (for example, if you wish to open a
Realm, check some property, and then possibly delete the Realm file and
re-open it), place the code which uses the Realm within an @autoreleasepool
{} and ensure you have no other references to it.

Warning:RLMRealm instances are not thread safe and can not be shared across
threads or dispatch queues. You must call this method on each thread you want
to interact with the Realm on. For dispatch queues, this means that you must
call it in each block which is dispatched, as a queue is not guaranteed to run
on a consistent thread.

Parameters

BOOL indicating if this Realm is read-only (must use for read-only files)

error

If an error occurs, upon return contains an NSError object
that describes the problem. If you are not interested in
possible errors, pass in NULL.

Return Value

An encrypted RLMRealm instance.

Discussion

The on-disk storage for encrypted Realms are encrypted using AES256+HMAC-SHA2,
but otherwise they behave like normal persisted Realms.

Encrypted Realms currently cannot be opened while lldb is attached to the
process due to that lldb does have an option to pass through mach exceptions to
the process being debugged. Attempting to open an encrypted Realm with lldb
attached will result in an EXC_BAD_ACCESS.

Declared In

RLMRealm.h

inMemoryRealmWithIdentifier:

Obtains an RLMRealm instance for an un-persisted in-memory Realm. The identifier
used to create this instance can be used to access the same in-memory Realm from
multiple threads.

+ (instancetype)inMemoryRealmWithIdentifier:(NSString *)identifier

Parameters

identifier

A string used to identify a particular in-memory Realm.

Return Value

An RLMRealm instance.

Discussion

Because in-memory Realms are not persisted, you must be sure to hold on to a
reference to the RLMRealm object returned from this for as long as you want
the data to last. Realm’s internal cache of RLMRealms will not keep the
in-memory Realm alive across cycles of the run loop, so without a strong
reference to the RLMRealm a new Realm will be created each time. Note that
RLMObjects, RLMArrays, and RLMResults that refer to objects persisted in a Realm have a
strong reference to the relevant RLMRealm, as do RLMNotifcationTokens.

Declared In

RLMRealm.h

migrateEncryptedRealmAtPath:key:

Performs the registered migration block on an encrypted Realm at the given path.

migrateRealmAtPath:

Parameters

Return Value

The error that occurred while applying the migration if any.

Discussion

This method is called automatically when opening a Realm for the first time and does
not need to be called explicitly. You can choose to call this method to control
exactly when and how migrations are performed.

See Also

Declared In

realmWithPath:

Parameters

path

Path to the file you want the data saved in.

Return Value

An RLMRealm instance.

Discussion

RLMRealm objects are cached internally by Realm, and calling this method
multiple times with the same path on a single thread within a single iteration
of the run loop on will normally return the same RLMRealm object.

Warning:RLMRealm instances are not thread safe and can not be shared across
threads or dispatch queues. You must call this method on each thread you want
to interact with the Realm on. For dispatch queues, this means that you must
call it in each block which is dispatched, as a queue is not guaranteed to run
on a consistent thread.

Declared In

RLMRealm.h

realmWithPath:readOnly:error:

Obtains an RLMRealm instance with persistence to a specific file with options.

Parameters

BOOL indicating if this Realm is read-only (must use for read-only files)

error

If an error occurs, upon return contains an NSError object
that describes the problem. If you are not interested in
possible errors, pass in NULL.

Return Value

An RLMRealm instance.

Discussion

Like realmWithPath, but with the ability to open read-only realms and get
errors as a NSError out parameter rather than exceptions.

Warning: Read-only Realms do not support changes made to the file while the
RLMRealm exists. This means that you cannot open a Realm as both read-only
and read-write at the same time. Read-only Realms should normally only be used
on files which cannot be opened in read-write mode, and not just for enforcing
correctness in code that should not need to write to the Realm.

Parameters

Return Value

The error that occurred while applying the migration, if any.

Discussion

Before you can open an existing RLMRealm which has a different on-disk schema
from the schema defined in your object interfaces you must provide a migration
block which converts from the disk schema to your current object schema. At the
minimum your migration block must initialize any properties which were added to
existing objects without defaults and ensure uniqueness if a primary key
property is added to an existing object.

You should call this method before accessing any RLMRealm instances which
require migration. After registering your migration block Realm will call your
block automatically as needed.

Warning: Unsuccessful migrations will throw exceptions when the migration block
is applied. This will happen in the following cases:

The migration block was run and returns a schema version which is not higher
than the previous schema version.

A new property without a default was added to an object and not initialized
during the migration. You are required to either supply a default value or to
manually populate added properties during a migration.

Discussion

NSString *notification: The name of the incoming notification. See
RLMRealmNotification for information on what
notifications are sent.

RLMRealm *realm: The realm for which this notification occurred

Declared In

RLMRealm.h

addObject:

Adds an object to be persisted it in this Realm.

- (void)addObject:(RLMObject *)object

Parameters

object

Object to be added to this Realm.

Discussion

Once added, this object can be retrieved using the objectsWhere: selectors
on RLMRealm and on subclasses of RLMObject. When added, all linked (child)
objects referenced by this object will also be added to the Realm if they are
not already in it. If the object or any linked objects already belong to a
different Realm an exception will be thrown. Use
[RLMObject createInRealm:withObject] to insert a copy of a persisted object
into a different Realm.

The object to be added must be valid and cannot have been previously deleted
from a Realm (i.e. isInvalidated) must be false.

Declared In

RLMRealm.h

addObjects:

Adds objects in the given array to be persisted it in this Realm.

- (void)addObjects:(id<NSFastEnumeration>)array

Parameters

array

An enumerable object such as NSArray or RLMResults which contains objects to be added to
this Realm.

Discussion

See Also

Declared In

RLMRealm.h

addOrUpdateObject:

Adds or updates an object to be persisted it in this Realm. The object provided must have a designated
primary key. If no objects exist in the RLMRealm instance with the same primary key value, the object is
inserted. Otherwise, the existing object is updated with any changed values.

Discussion

See Also

Declared In

RLMRealm.h

beginWriteTransaction

Begins a write transaction in an RLMRealm.

- (void)beginWriteTransaction

Discussion

Only one write transaction can be open at a time. Write transactions cannot be
nested, and trying to begin a write transaction on a RLMRealm which is
already in a write transaction with throw an exception. Calls to
beginWriteTransaction from RLMRealm instances in other threads will block
until the current write transaction completes.

Before beginning the write transaction, beginWriteTransaction updates the
RLMRealm to the latest Realm version, as if refresh was called, and
generates notifications if applicable. This has no effect if the RLMRealm
was already up to date.

It is rarely a good idea to have write transactions span multiple cycles of
the run loop, but if you do wish to do so you will need to ensure that the
RLMRealm in the write transaction is kept alive until the write transaction
is committed.

Declared In

RLMRealm.h

cancelWriteTransaction

Revert all writes made in the current write transaction and end the transaction.

- (void)cancelWriteTransaction

Discussion

This rolls back all objects in the Realm to the state they were in at the
beginning of the write transaction, and then ends the transaction.

This restores the data for deleted objects, but does not re-validated deleted
accessor objects. Any RLMObjects which were added to the Realm will be
invalidated rather than switching back to standalone objects.
Given the following code:

Parameters

Declared In

invalidate

Discussion

An RLMRealm holds a read lock on the version of the data accessed by it, so
that changes made to the Realm on different threads do not modify or delete the
data seen by this RLMRealm. Calling this method releases the read lock,
allowing the space used on disk to be reused by later write transactions rather
than growing the file. This method should be called before performing long
blocking operations on a background thread on which you previously read data
from the Realm which you no longer need.

All RLMObject, RLMResults and RLMArray instances obtained from this
RLMRealm on the current thread are invalidated, and can not longer be used.
The RLMRealm itself remains valid, and a new read transaction is implicitly
begun the next time data is read from the Realm.

Calling this method multiple times in a row without reading any data from the
Realm, or before ever reading any data from the Realm is a no-op. This method
cannot be called on a read-only Realm.

Declared In

RLMRealm.h

refresh

Update an RLMRealm and outstanding objects to point to the most recent data for this RLMRealm.

- (BOOL)refresh

Return Value

Whether the realm had any updates. Note that this may return YES even if no data has actually changed.

Declared In

writeCopyToPath:error:

Parameters

path

Path to save the Realm to.

error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

YES if the realm was copied successfully. Returns NO if an error occurred.

Discussion

The destination file cannot already exist.

Note that if this is called from within a write transaction it writes the
current data, and not data when the last write transaction was committed.