Threading - Swift SDK

Aguarde a conclusão das escritas assíncronas

O SDK fornece um Bool para sinalizar se o Realm está executando uma gravação assíncrona no momento. A variável isPerformingAsynchronousWriteOperations se torna true após uma chamada para um dos seguintes:

• writeAsync

• beginAsyncWrite

• commitAsyncWrite

Permanece verdadeiro até que todas as operações de gravação assíncronas programadas sejam concluídas. Embora isso seja verdade, isso bloqueia o fechamento ou invalidação do domínio.

Confirme ou cancele uma escrita assíncrona

Para concluir uma escrita assíncrona, você ou o SDK devem chamar:

• commitAsyncWrite

• cancelAsyncWrite

Quando você usa o método writeAsync, o SDK cuida da confirmação ou do cancelamento da transação. Isso fornece a conveniência da gravação assíncrona sem a necessidade de manter manualmente o estado vinculado ao escopo do objeto. No entanto, enquanto estiver no bloco writeAsync , você pode chamar explicitamente commitAsyncWrite ou cancelAsyncWrite. Se você retornar sem chamar um desses métodos, writeAsync :

• Realiza a gravação após executar as instruções no bloco de gravação.

• Retorna um erro

Em ambos os casos, isto conclui a operação writeAsync.

Para ter mais controle sobre quando confirmar ou cancelar a transação de gravação assíncrona, use o método beginAsyncWrite. Ao usar este método, você deve confirmar explicitamente as transações. Retornar sem confirmar uma gravação assíncrona cancela a transação. beginAsyncWrite retorna um ID que você pode passar para cancelAsyncWrite.

commitAsyncWrite confirma de forma assíncrona uma transação de gravação. Esta é a etapa que persiste os dados no domínio. commitAsyncWrite pode levar um bloco onComplete. Este bloco é executado no thread de origem quando o commit é concluído ou falha com um erro.

A chamada de commitAsyncWrite retorna imediatamente. Isso permite que o chamador continue enquanto o SDK executa a E/S em um thread em segundo plano. Esse método retorna um ID que você pode passar para cancelAsyncWrite. Isso cancela a invocação pendente do bloco de conclusão. Não cancela a confirmação em si.

Você pode agrupar chamadas sequenciais para commitAsyncWrite. O agrupamento dessas chamadas em lote melhora o desempenho de gravação; especialmente quando as transações em lote são pequenas. Para permitir o agrupamento de transações, configure o parâmetro isGroupingAllowed como true.

Você pode ligar para cancelAsyncWrite em beginAsyncWrite ou commitAsyncWrite. Quando você chama beginAsyncWrite, isso cancela toda a transação de escrita. Quando você o chama commitAsyncWrite, isso cancela apenas um bloco de onComplete que você pode ter passado para commitAsyncWrite. Não cancela a confirmação em si. Você precisa do ID do beginAsyncWrite ou do commitAsyncWrite que deseja cancelar.

Crie uma fila em série para usar o Realm em uma thread em background

Ao usar o Realm em uma conversa de fundo, crie uma fila de série. O Realm não é compatível com o uso de realms em filas simultâneas, como a fila global().

// Initialize a serial queue, and
// perform realm operations on it
let serialQueue = DispatchQueue(label: "serial-queue")
serialQueue.async {
    let realm = try! Realm(configuration: .defaultConfiguration, queue: serialQueue)
    // Do something with Realm on the non-main thread
}

Passe instâncias entre threads

As instâncias de Realm, Results, Liste Objects gerenciadas são confinadas por thread. Isso significa que você só pode usá-las no tópico onde as criou. No entanto, o Realm fornece um mecanismo chamado referências thread-safe que permite copiar uma instância criada em um thread para outro thread.

let realm = try! Realm()
let person = Person(name: "Jane")
try! realm.write {
    realm.add(person)
}
// Create thread-safe reference to person
@ThreadSafe var personRef = person
// @ThreadSafe vars are always optional. If the referenced object is deleted,
// the @ThreadSafe var will be nullified.
print("Person's name: \(personRef?.name ?? "unknown")")
// Pass the reference to a background thread
DispatchQueue(label: "background", autoreleaseFrequency: .workItem).async {
    let realm = try! Realm()
    try! realm.write {
        // Resolve within the transaction to ensure you get the
        // latest changes from other threads. If the person
        // object was deleted, personRef will be nil.
        guard let person = personRef else {
            return // person was deleted
        }
        person.name = "Jane Doe"
    }
}

func someLongCallToGetNewName() async -> String {
    return "Janet"
}
@MainActor
func loadNameInBackground(@ThreadSafe person: Person?) async {
    let newName = await someLongCallToGetNewName()
    let realm = try! await Realm()
    try! realm.write {
        person?.name = newName
    }
}
@MainActor
func createAndUpdatePerson() async {
    let realm = try! await Realm()
    
    let person = Person(name: "Jane")
    try! realm.write {
        realm.add(person)
    }
    await loadNameInBackground(person: person)
}
await createAndUpdatePerson()

let person = Person(name: "Jane")
let realm = try! Realm()
try! realm.write {
    realm.add(person)
}
// Create thread-safe reference to person
let personRef = ThreadSafeReference(to: person)
// Pass the reference to a background thread
DispatchQueue(label: "background", autoreleaseFrequency: .workItem).async {
    let realm = try! Realm()
    try! realm.write {
        // Resolve within the transaction to ensure you get the latest changes from other threads
        guard let person = realm.resolve(personRef) else {
            return // person was deleted
        }
        person.name = "Jane Doe"
    }
}

extension Realm {
    func writeAsync<T: ThreadConfined>(_ passedObject: T, errorHandler: @escaping ((_ error: Swift.Error) -> Void) = { _ in return }, block: @escaping ((Realm, T?) -> Void)) {
        let objectReference = ThreadSafeReference(to: passedObject)
        let configuration = self.configuration
        DispatchQueue(label: "background", autoreleaseFrequency: .workItem).async {
            do {
                let realm = try Realm(configuration: configuration)
                try realm.write {
                    // Resolve within the transaction to ensure you get the latest changes from other threads
                    let object = realm.resolve(objectReference)
                    block(realm, object)
                }
            } catch {
                errorHandler(error)
            }
        }
    }
}

let realm = try! Realm()
let readEmails = realm.objects(Email.self).where {
    $0.read == true
}
realm.writeAsync(readEmails) { (realm, readEmails) in
    guard let readEmails = readEmails else {
        // Already deleted
        return
    }
    realm.delete(readEmails)
}

Use o mesmo Realm em todos os threads

Não é possível compartilhar instâncias de realm entre threads.

Para usar o mesmo arquivo domínio em todos os threads, abra uma instância de domínio diferente em cada thread. Contanto que você use a mesma configuração, todas as instâncias do domínio serão mapeadas para o mesmo arquivo no disco.

Atualização de Realms

Quando você abre um realm, ele reflete a mais recente confirmação de gravação bem-sucedida e permanece nessa versão até ser atualizado. Isso significa que o realm não verá as mudanças que aconteceram em outro thread até a próxima atualização. Um realm no thread da UI -- mais precisamente, em qualquer thread de loop de eventos -- atualiza-se automaticamente no início do loop desse thread. No entanto, você deve atualizar manualmente as instâncias do realm que não existem em threads de loop ou que têm a atualização automática desativada.

if (![realm autorefresh]) {
    [realm refresh]
}

if (!realm.autorefresh) {
   // Manually refresh
   realm.refresh()
}

Objetos congelados

Objetos vivos, confinados ao thread, funcionam bem na maioria dos casos. No entanto, alguns aplicativos -- aqueles baseados em arquiteturas reativas, baseadas em fluxo de eventos, por exemplo -- precisam enviar cópias imutáveis para vários threads para processamento antes de, finalmente, terminarem no thread da UI. Fazer uma cópia profunda toda vez seria caro, e o Realm não permite que instâncias vivas sejam compartilhadas entre threads. Nesse caso, você pode congelar e descongelar objetos, collections e realms.

O congelamento cria uma visão imutável de um objeto, collection ou domínio específico. O objeto, collection ou realm congelado ainda existe no disco e não precisa ser copiado profundamente quando passado para outros segmentos. Você pode compartilhar livremente o objeto congelado entre threads sem se preocupar com problemas de thread. Quando você congela um realm, seus objetos filhos também ficam congelados.

Objetos congelados não estão ativos e não são atualizados automaticamente. Eles são efetivamente snapshots do estado do objeto no momento do congelamento. Descongelar um objeto retorna uma versão ativa do objeto congelado.

// Get an immutable copy of the realm that can be passed across threads
RLMRealm *frozenRealm = [realm freeze];
RLMResults *dogs = [Dog allObjectsInRealm:realm];
// You can freeze collections
RLMResults *frozenDogs = [dogs freeze];
// You can still read from frozen realms
RLMResults *frozenDogs2 = [Dog allObjectsInRealm:frozenRealm];
Dog *dog = [dogs firstObject];
// You can freeze objects
Dog *frozenDog = [dog freeze];
// To modify frozen objects, you can thaw them
// You can thaw collections
RLMResults *thawedDogs = [dogs thaw];
// You can thaw objects
Dog *thawedDog = [dog thaw];
// You can thaw frozen realms
RLMRealm *thawedRealm = [realm thaw];

let realm = try! Realm()
// Get an immutable copy of the realm that can be passed across threads
let frozenRealm = realm.freeze()
assert(frozenRealm.isFrozen)
let people = realm.objects(Person.self)
// You can freeze collections
let frozenPeople = people.freeze()
assert(frozenPeople.isFrozen)
// You can still read from frozen realms
let frozenPeople2 = frozenRealm.objects(Person.self)
assert(frozenPeople2.isFrozen)
let person = people.first!
assert(!person.realm!.isFrozen)
// You can freeze objects
let frozenPerson = person.freeze()
assert(frozenPerson.isFrozen)
// Frozen objects have a reference to a frozen realm
assert(frozenPerson.realm!.isFrozen)

Quando estiver trabalhando com objetos congelados, uma tentativa de realizar qualquer uma das seguintes ações gera uma exceção:

• Abrir uma transação de gravação em um realm congelado.

• Modificar um objeto congelado.

• Adicionar um ouvinte de alteração a um realm, collection ou objeto congelado.

Você pode utilizar isFrozen para verificar se o objeto está congelado. Isso é sempre seguro para threads.

if ([realm isFrozen]) {
    // ...
}

if (realm.isFrozen) {
    // ...
}

Objetos congelados continuam válidos desde que o domínio ativo que os gerou permaneça aberto. Portanto evite fechar o domínio ativo até que todas as threads tenham terminado com os objetos congelados. Você pode fechar um domínio congelado antes que o domínio ativo seja fechado.

// Read from a frozen realm
let frozenPeople = frozenRealm.objects(Person.self)
// The collection that we pull from the frozen realm is also frozen
assert(frozenPeople.isFrozen)
// Get an individual person from the collection
let frozenPerson = frozenPeople.first!
// To modify the person, you must first thaw it
// You can also thaw collections and realms
let thawedPerson = frozenPerson.thaw()
// Check to make sure this person is valid. An object is
// invalidated when it is deleted from its managing realm,
// or when its managing realm has invalidate() called on it.
assert(thawedPerson?.isInvalidated == false)
// Thawing the person also thaws the frozen realm it references
assert(thawedPerson!.realm!.isFrozen == false)
// Let's make the code easier to follow by naming the thawed realm
let thawedRealm = thawedPerson!.realm!
// Now, you can modify the todo
try! thawedRealm.write {
   thawedPerson!.name = "John Michael Kane"
}

// Get a copy of frozen objects.
// Here, we're getting them from a frozen realm,
// but you might also be passing them across threads.
let frozenTimmy = frozenRealm.objects(Person.self).where {
    $0.name == "Timmy"
}.first!
let frozenLassie = frozenRealm.objects(Dog.self).where {
    $0.name == "Lassie"
}.first!
// Confirm the objects are frozen.
assert(frozenTimmy.isFrozen == true)
assert(frozenLassie.isFrozen == true)
// Thaw the frozen objects. You must thaw both the object
// you want to append and the collection you want to append it to.
let thawedTimmy = frozenTimmy.thaw()
let thawedLassie = frozenLassie.thaw()
let realm = try! Realm()
try! realm.write {
    thawedTimmy?.dogs.append(thawedLassie!)
}
XCTAssertEqual(thawedTimmy?.dogs.first?.name, "Lassie")

Comparação e contraste com Git

Se você está familiarizado com um sistema de controle de versão distribuído como o Git, talvez já tenha uma compreensão intuitiva do MVCC. Dois elementos fundamentais do Git são:

• Confirmações, que são escritas atômicas.

• Ramificações, que são versões diferentes do histórico de confirmações.

Da mesma forma, o Realm tem gravações confirmadas atomicamente na forma de transações. O Realm também tem muitas versões diferentes da história a qualquer momento, como ramificações.

Ao contrário do Git, que suporta ativamente a distribuição e a divergência por meio de forking, um realm só tem uma versão mais recente verdadeira em um determinado momento e sempre escreve para o head dessa versão mais recente. O Realm não pode escrever em uma versão anterior. Isso significa que seus dados convergem para uma versão mais recente da verdade.

Estrutura interna

Um domínio é implementado usando uma estrutura de dados B+tree.. O nó de alto nível representa uma versão do domínio; nós secundários são objetos nessa versão do domínio. O domínio tem um ponteiro para sua versão mais recente, assim como o Git tem um ponteiro para sua confirmação de CABEÇALHO.

O Realm usa uma técnica de cópia em gravação para garantir isolamento e durabilidade. Quando você faz alterações, o Realm copia a parte relevante da árvore para gravar. Em seguida, Realm confirma as alterações em duas fases:

• O Realm escreve as alterações no disco e verifica se foi feito.

• Em seguida, o Realm coloca o ponteiro da versão mais recente apontando para a versão recém-escrita.

Esse processo de confirmação em duas etapas garante que, mesmo que a gravação falhe parcialmente, a versão original não será corrompida de forma alguma, pois as alterações foram feitas em uma cópia da parte relevante da árvore. Da mesma forma, o ponteiro raiz do domínio apontará para a versão original até que a nova versão seja válida.

Exemplo

O diagrama a seguir ilustra o processo de confirmação:

clique para ampliar

1. O realm é estruturado como uma árvore. O realm tem um ponteiro para a sua última versão, V1.

2. Ao escrever, o Realm cria uma nova versão V2 com base na V1. Realm faz cópias de objetos para modificação (A 1 , C ¹), enquanto links para objetos não modificados continuam a apontar para as versões originais (B, D).

3. Após validar o commit, o Realm atualiza o ponteiro para a nova versão mais recente, V2. O Realm então descarta nós antigos que não estão mais conectados à árvore.

Realm usa técnicas de cópia zero, como mapeamento de memória, para lidar com dados. Quando você lê um valor do realm, você está virtualmente olhando para o valor no disco real, não uma cópia dele. Esta é a base para objetos vivos. É também por isso que um ponteiro de head de realm pode ser definido para apontar para a nova versão depois que a gravação no disco tiver sido validada.