Open realm async

CHANGELOG.md

@@ -7,6 +7,7 @@
  * Added `Transaction` which is a class that exposes an API for committing and rolling back an active transaction.
  * Added `realm.beginWriteAsync` which returns a `Future<Transaction>` that resolves when the write lock has been obtained.
  * Added `realm.writeAsync` which opens an asynchronous transaction, invokes the provided callback, then commits the transaction asynchronously.
+* Support `Realm.open` API to asynchronously open a local or synced Realm. When opening a synchronized Realm it will download all the content available at the time the operation began and then return a usable Realm. ([#731](https://github.com/realm/realm-dart/pull/731))
 
 ### Fixed
 * Added more validations when using `User.apiKeys` to return more meaningful errors when the user cannot perform API key actions - e.g. when the user has been logged in with API key credentials or when the user has been logged out. (Issue [#950](https://github.com/realm/realm-dart/issues/950))

ffigen/README.md

@@ -3,7 +3,7 @@ The is executed manually as needed and this package is never published.
 
 Usage: 
 
-dart run ffigen
+dart run ffigen --config config.yaml
 
 On linux you may need to install clang 11 dev tools. If you are using apt-get you can do:
 ```

flutter/realm_flutter/pubspec.yaml

@@ -34,7 +34,7 @@ dependencies:
  tar: ^0.5.4
  build_runner: ^2.1.0
  http: ^0.13.4
- cancellation_token: ^1.4.0
+ cancellation_token: ^1.5.0
 
 dev_dependencies:
  flutter_test:

lib/src/native/realm_core.dart

@@ -1831,20 +1831,24 @@ class _RealmCore {
  return completer.future;
  }
 
- Future<void> sessionWaitForDownload(Session session) {
- final completer = Completer<void>();
- final callback = Pointer.fromFunction<Void Function(Handle, Pointer<realm_sync_error_code_t>)>(_sessionWaitCompletionCallback);
- final userdata = _realmLib.realm_dart_userdata_async_new(completer, callback.cast(), scheduler.handle._pointer);
- _realmLib.realm_sync_session_wait_for_download_completion(session.handle._pointer, _realmLib.addresses.realm_dart_sync_wait_for_completion_callback,
- userdata.cast(), _realmLib.addresses.realm_dart_userdata_async_free);
+ Future<void> sessionWaitForDownload(Session session, [CancellationToken? cancellationToken]) {
+ final completer = CancellableCompleter<void>(cancellationToken);
+ if (!completer.isCancelled) {
+ final callback = Pointer.fromFunction<Void Function(Handle, Pointer<realm_sync_error_code_t>)>(_sessionWaitCompletionCallback);
+ final userdata = _realmLib.realm_dart_userdata_async_new(completer, callback.cast(), scheduler.handle._pointer);
+ _realmLib.realm_sync_session_wait_for_download_completion(session.handle._pointer, _realmLib.addresses.realm_dart_sync_wait_for_completion_callback,
+ userdata.cast(), _realmLib.addresses.realm_dart_userdata_async_free);
+ }
  return completer.future;
  }
 
  static void _sessionWaitCompletionCallback(Object userdata, Pointer<realm_sync_error_code_t> errorCode) {
  final completer = userdata as Completer<void>;
-
+ if (completer.isCompleted) {
+ return;
+ }
  if (errorCode != nullptr) {
- // Throw RealmException instead of RealmError to be recoverable by the user.
+  // Throw RealmException instead of RealmError to be recoverable by the user.
  completer.completeError(RealmException(errorCode.toSyncError().toString()));
  } else {
  completer.complete();

lib/src/realm_class.dart

@@ -20,10 +20,10 @@ import 'dart:async';
 import 'dart:ffi';
 import 'dart:io';
 
-import 'package:cancellation_token/cancellation_token.dart';
 import 'package:logging/logging.dart';
 import 'package:realm_common/realm_common.dart';
 import 'package:collection/collection.dart';
+import 'package:cancellation_token/cancellation_token.dart';
 
 import 'configuration.dart';
 import 'list.dart';
@@ -61,8 +61,6 @@ export 'package:realm_common/realm_common.dart'
  ObjectId,
  Uuid;
 
-export 'package:cancellation_token/cancellation_token.dart' show CancellationToken, CancelledException;
-
 // always expose with `show` to explicitly control the public API surface
 export 'app.dart' show AppConfiguration, MetadataPersistenceMode, App, AppException;
 export "configuration.dart"
@@ -89,6 +87,7 @@ export 'subscription.dart' show Subscription, SubscriptionSet, SubscriptionSetSt
 export 'user.dart' show User, UserState, UserIdentity, ApiKeyClient, ApiKey;
 export 'session.dart' show Session, SessionState, ConnectionState, ProgressDirection, ProgressMode, SyncProgress, ConnectionStateChange;
 export 'migration.dart' show Migration;
+export 'package:cancellation_token/cancellation_token.dart' show CancellationToken, CancelledException;
 
 /// A [Realm] instance represents a `Realm` database.
 ///
@@ -120,6 +119,42 @@ class Realm implements Finalizable {
  _populateMetadata();
  }
 
+ /// A method for asynchronously opening a [Realm].
+ ///
+ /// When the configuration is [FlexibleSyncConfiguration], the realm will be downloaded and fully
+ /// synchronized with the server prior to the completion of the returned [Future].
+ /// This method could be called also for opening a local [Realm] with [LocalConfiguration].
+ ///
+ /// * `config`- a configuration object that describes the realm.
+ /// * `cancellationToken` - an optional [CancellationToken] used to cancel the operation.
+ /// * `onProgressCallback` - a callback for receiving download progress notifications for synced [Realm]s.
+ ///
+ /// Returns `Future<Realm>` that completes with the [Realm] once the remote [Realm] is fully synchronized or with a [CancelledException] if operation is canceled.
+ /// When the configuration is [LocalConfiguration] this completes right after the local [Realm] is opened.
+ /// Using [open] for opening a local Realm is equivalent to using the constructor of [Realm].
+ static Future<Realm> open(Configuration config, {CancellationToken? cancellationToken, ProgressCallback? onProgressCallback}) async {
+ if (cancellationToken != null && cancellationToken.isCancelled) {
+ throw cancellationToken.exception;
+ }
+ final realm = Realm(config);
+ StreamSubscription<SyncProgress>? subscription;
+ try {
+ if (config is FlexibleSyncConfiguration) {
+ final session = realm.syncSession;
+ if (onProgressCallback != null) {
+ subscription = session.getProgressStream(ProgressDirection.download, ProgressMode.forCurrentlyOutstandingWork).listen(onProgressCallback);
+ }
+ await session.waitForDownload(cancellationToken);
+ await subscription?.cancel();
+ }
+ } catch (_) {
+ await subscription?.cancel();
+ realm.close();
+ rethrow;
+ }
+ return await CancellableFuture.value(realm, cancellationToken);
+ }
+
  static RealmHandle _openRealm(Configuration config) {
  var dir = File(config.path).parent;
  if (!dir.existsSync()) {
@@ -752,3 +787,10 @@ class MigrationRealm extends DynamicRealm {
 
  MigrationRealm._(Realm realm) : super._(realm);
 }
+
+/// The signature of a callback that will be executed while the Realm is opened asynchronously with [Realm.open].
+/// This is the registered onProgressCallback when calling [open] that receives progress notifications while the download is in progress.
+///
+/// * syncProgress - an object of [SyncProgress] that contains `transferredBytes` and `transferableBytes`.
+/// {@category Realm}
+typedef ProgressCallback = void Function(SyncProgress syncProgress);

lib/src/session.dart

@@ -18,7 +18,6 @@
 
 import 'dart:async';
 import 'dart:ffi';
-
 import '../realm.dart';
 import 'native/realm_core.dart';
 import 'user.dart';
@@ -61,7 +60,7 @@ class Session implements Finalizable {
  Future<void> waitForUpload() => realmCore.sessionWaitForUpload(this);
 
  /// Waits for the [Session] to finish all pending downloads.
- Future<void> waitForDownload() => realmCore.sessionWaitForDownload(this);
+ Future<void> waitForDownload([CancellationToken? cancellationToken]) => realmCore.sessionWaitForDownload(this, cancellationToken);
 
  /// Gets a [Stream] of [SyncProgress] that can be used to track upload or download progress.
  Stream<SyncProgress> getProgressStream(ProgressDirection direction, ProgressMode mode) {
@@ -204,7 +203,7 @@ class SessionProgressNotificationsController {
  }
 
  void _stop() {
- if (_token == null) {
+ if (_token == null || _session._handle.released) {
  return;
  }
 

pubspec.yaml

@@ -31,7 +31,7 @@ dependencies:
  tar: ^0.5.4
  build_runner: ^2.1.0
  http: ^0.13.4
- cancellation_token: ^1.4.0
+ cancellation_token: ^1.5.0
 
 dev_dependencies:
  build_cli: ^2.2.0

test/configuration_test.dart

@@ -542,7 +542,7 @@ Future<void> main([List<String>? args]) async {
 
  final schema = [Task.schema];
  final flexibleSyncConfig = Configuration.flexibleSync(user, schema, path: realmPath);
- final realm = Realm(flexibleSyncConfig);
+ final realm = getRealm(flexibleSyncConfig);
  final oid = ObjectId();
  realm.subscriptions.update((mutableSubscriptions) {
  mutableSubscriptions.add(realm.query<Task>(r'_id == $0', [oid]));