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 a 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 Realm em todos os threads, abra uma instância de realm diferente em cada thread. Contanto que você use a mesma configuração, todas as instâncias do Realm 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.

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.

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.

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, você já pode ter 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 realm é implementado usando uma árvore B+ estrutura de dados. O nó de nível superior representa uma versão do domínio; nós filhos são objetos nessa versão do realm. O realm tem um ponteiro para sua versão mais recente, da mesma forma que o Git tem um ponteiro para seu commit HEAD.

A Realm usa uma técnica de cópia em gravação para garantir o isolamento e durabilidade . Quando você faz alterações, o Realm copia a parte relevante da árvore para escrever. O Realm então 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.