Merge pull request #64 from filiph/fix/deprecate-shutdown

Deprecate shutdown

CHANGELOG.md

@@ -68,6 +68,12 @@ to `2.0.0-pre.2` and beyond.
   );
   soloud.play(source);
   ```
+
+- Deprecated `shutdown()`. Replaced with the synchronous `deinit()`.
+  Quick fix available.
+- Renamed `initialize()` to `init()`, in order to come closer to the original
+  C++ API, and also to have a symmetry (`init`/`deinit`).
+  Quick fix available.
 
 #### 2.0.0-pre.1 (12 Mar 2024)
 - added `looping` and `loopingStartAt` properties to `SoLoud.play()` and `SoLoud.play3d()`.

example/lib/main.dart

@@ -30,7 +30,7 @@ void main() async {
   });
 
   /// Initialize the player
-  await SoLoud.instance.initialize().then(
+  await SoLoud.instance.init().then(
     (_) {
       Logger('main').info('player started');
       SoLoud.instance.setVisualizationEnabled(true);
@@ -55,7 +55,7 @@ class MyApp extends StatefulWidget {
 class _MyAppState extends State<MyApp> {
   @override
   void dispose() {
-    SoLoud.instance.shutdown();
+    SoLoud.instance.deinit();
     super.dispose();
   }
 

example/lib/main_wav_stream.dart

@@ -70,7 +70,7 @@ class _MyHomePageState extends State<MyHomePage> {
 
   Future<void> start() async {
     try {
-      await SoLoud.instance.initialize();
+      await SoLoud.instance.init();
     } catch (e) {
       debugPrint('isolate starting error: $e');
       return;
@@ -110,7 +110,7 @@ class _MyHomePageState extends State<MyHomePage> {
   }
 
   Future<void> stop() async {
-    await SoLoud.instance.shutdown();
+    SoLoud.instance.deinit();
     SoLoudCapture.instance.stopCapture();
     sounds.clear();
   }

example/tests/tests.dart

@@ -152,7 +152,7 @@ Future<void> test6() async {
     'The protected song has been stopped!',
   );
 
-  await dispose();
+  dispose();
 }
 
 /// Test allInstancesFinished stream
@@ -203,7 +203,7 @@ Future<void> test5() async {
   assert(explosionDisposed, "Explosion sound wasn't disposed.");
   assert(songDisposed, "Song sound wasn't disposed.");
 
-  await dispose();
+  dispose();
 }
 
 /// Test synchronous `deinit()`
@@ -212,7 +212,7 @@ Future<void> test4() async {
   for (var t = 100; t >= 0; t -= 5) {
     /// Initialize the player
     var error = '';
-    await SoLoud.instance.initialize().then(
+    await SoLoud.instance.init().then(
       (_) {},
       onError: (Object e) {
         e = 'TEST FAILED delay: $t. Player starting error: $e';
@@ -242,7 +242,7 @@ Future<void> test4() async {
   /// waiting for `initialize()` to finish
   for (var t = 50; t >= 0; t -= 2) {
     /// Initialize the player
-    unawaited(SoLoud.instance.initialize());
+    unawaited(SoLoud.instance.init());
 
     /// wait for [t] ms and deinit()
     await Future.delayed(Duration(milliseconds: t), () {});
@@ -258,7 +258,7 @@ Future<void> test4() async {
   }
 
   /// Try init-play-deinit and again init-play without disposing the sound
-  await SoLoud.instance.initialize();
+  await SoLoud.instance.init();
 
   await loadAsset();
   await SoLoud.instance.play(currentSound!);
@@ -273,7 +273,7 @@ Future<void> test4() async {
 
   /// Initialize again and check if the sound has been
   /// disposed correctly by `deinit()`
-  await SoLoud.instance.initialize();
+  await SoLoud.instance.init();
   assert(
     SoLoudController()
             .soLoudFFI
@@ -333,7 +333,7 @@ Future<void> test3() async {
     await delay(300);
   }
 
-  await dispose();
+  dispose();
 }
 
 /// Test play, pause, seek, position
@@ -365,7 +365,7 @@ Future<void> test2() async {
     assert(position == wantedPosition, 'getPosition() failed!');
   }
 
-  await dispose();
+  dispose();
 }
 
 /// Test start/stop isolate, load, play and events from sound
@@ -420,7 +420,7 @@ Future<void> test1() async {
   {
     /// Stop player and see in log:
     /// "@@@@@@@@@@@ SOUND EVENT: SoundEvent.soundDisposed .*"
-    await dispose();
+    dispose();
     assert(
       output == 'SoundEvent.soundDisposed',
       'Sound end playback event not triggered!',
@@ -430,12 +430,11 @@ Future<void> test1() async {
 
 /// Common methods
 Future<void> initialize() async {
-  await SoLoud.instance.initialize();
+  await SoLoud.instance.init();
 }
 
-Future<void> dispose() async {
-  final ret = await SoLoud.instance.shutdown();
-  assert(ret, 'dispose() failed!');
+void dispose() {
+  SoLoud.instance.deinit();
 }
 
 Future<void> loadAsset() async {

lib/fix_data.yaml

@@ -9,6 +9,28 @@
 version: 1
 
 transforms:
+  # SoLoud.initialize => SoLoud.init
+  - title: "Rename to 'init'"
+    date: 2024-03-20
+    element:
+      uris: [ 'flutter_soloud.dart', 'package:flutter_soloud/flutter_soloud.dart' ]
+      method: 'initialize'
+      inClass: 'SoLoud'
+    changes:
+      - kind: 'rename'
+        newName: 'init'
+
+  # SoLoud.shutdown => SoLoud.deinit
+  - title: "Rename to 'deinit'"
+    date: 2024-03-20
+    element:
+      uris: [ 'flutter_soloud.dart', 'package:flutter_soloud/flutter_soloud.dart' ]
+      method: 'shutdown'
+      inClass: 'SoLoud'
+    changes:
+      - kind: 'rename'
+        newName: 'deinit'
+
   # AudioSource.handle => AudioSource.handles
   - title: "Rename to 'handles'"
     date: 2024-03-11

lib/src/exceptions/exceptions_from_dart.dart

@@ -38,18 +38,14 @@ class SoLoudInitializationTimedOutException extends SoLoudDartException {
   String get description => 'The engine took too long to initialize.';
 }
 
-/// An exception that is thrown when the SoLoud engine fails to shutdown.
-/// This is not thrown during normal shutdown, but it _can_ be thrown if
-/// `initialize()` was called at a time of shutdown, and that shutdown failed.
-class ShutdownFailedException extends SoLoudDartException {
-  /// Creates a new [ShutdownFailedException].
-  const ShutdownFailedException([super.message]);
+/// An exception that is thrown when the SoLoud engine initialization
+/// is cut short by a call to `SoLoud.deinit()`.
+class SoLoudInitializationStoppedByDeinitException extends SoLoudDartException {
+  /// Creates a new [SoLoudInitializationStoppedByDeinitException].
+  const SoLoudInitializationStoppedByDeinitException([super.message]);
 
   @override
-  String get description => 'The engine failed to shut down. '
-      'This is not thrown during normal shutdown, but it _can_ be thrown if '
-      '`initialize()` was called at a time of a shutdown in progress, '
-      'and that shutdown failed.';
+  String get description => 'SoLoud.deinit() was called during initialization.';
 }
 
 /// An exception that is thrown when the temporary folder fails to be created