DriftIsolate.inCurrent constructor

DriftIsolate.inCurrent(
  1. DatabaseOpener opener, {
  2. bool killIsolateWhenDone = false,
  3. bool serialize = false,
  4. bool shutdownAfterLastDisconnect = false,
  5. ReceivePort? port,
  6. void beforeShutdown()?,
})

Creates a DriftIsolate in the Isolate.current isolate. The returned DriftIsolate is an object than can be sent across isolates - any other isolate can then use DriftIsolate.connect to obtain a special database connection which operations are all executed on this isolate.

When killIsolateWhenDone is enabled (it defaults to false) and shutdownAll is called on the returned DriftIsolate, the isolate used to call DriftIsolate.inCurrent will be killed.

Internally, drift uses ports from dart:isolate to send commands to an internal server dispatching database actions. In most setups, those ports can send and receive almost any Dart object. In special cases though, the platform only supports sending simple types across send types. In particular, isolates across different Flutter engines (such as the ones spawned by the workmanager package) are unable to handle most objects. To support those setups, drift can serialize its iground isolate doing all the work. Any other isolate can use the connect method to obtain an instance of a GeneratedDatabase class that will delegate its work onto a background isolate. Auto-updating queries, and transactions work across isolates, and the user facing api is exactly the same.

Please note that, while running drift in a background isolate can reduce lags in foreground isolates (thus removing UI jank), the overall database performance will be worse. This is because result data is not available directly and instead needs to be copied from the database isolate. Thanks to recent improvements like isolate groups in the Dart VM, this overhead is fairly small and using isolates to run drift queries is recommended where possible.

The easiest way to use drift isolates is to use NativeDatabase.createInBackground, which is a dropternal communication channel to only send simple types across isolates. The serialize parameter, which is enabled by default, controls this behavior.

In most scenarios, serialize can be disabled for a considerable performance improvement.

Implementation

factory DriftIsolate.inCurrent(
  DatabaseOpener opener, {
  bool killIsolateWhenDone = false,
  bool serialize = false,
  bool shutdownAfterLastDisconnect = false,
  ReceivePort? port,
  void Function()? beforeShutdown,
}) {
  final server = RunningDriftServer(
    Isolate.current,
    opener(),
    killIsolateWhenDone: killIsolateWhenDone,
    port: port,
    beforeShutdown: beforeShutdown,
    shutDownAfterLastDisconnect: shutdownAfterLastDisconnect,
  );
  return DriftIsolate.fromConnectPort(
    server.portToOpenConnection,
    serialize: serialize,
  );
}