Rename shutdown to terminate and publish it. (#3694)

* Rename shutdown to terminate and publish it.

* Addressing feedbacks

Author: wu-hui

Firestore/CHANGELOG.md

@@ -5,6 +5,10 @@
 - [feature] Added a `waitForPendingWrites()` method to `FIRFirestore` class
   which allows users to wait on a promise that resolves when all pending
   writes are acknowledged by the Firestore backend.
+- [feature] Added a `terminate()` method to `FIRFirestore` which terminates
+  the instance, releasing any held resources. Once it completes, you can
+  optionally call `clearPersistence()` to wipe persisted Firestore data
+  from disk.
 
 # v1.4.5
 - [fixed] Fixed a crash that would happen when changing networks or going from

Firestore/Example/Tests/Integration/API/FIRDatabaseTests.mm

@@ -1224,21 +1224,21 @@ - (void)testCanDisableNetwork {
   [self awaitExpectations];
 }
 
-- (void)testClientCallsAfterShutdownFail {
+- (void)testClientCallsAfterTerminationFail {
   FIRDocumentReference *doc = [self documentRef];
   FIRFirestore *firestore = doc.firestore;
 
   [firestore enableNetworkWithCompletion:[self completionForExpectationWithName:@"Enable network"]];
   [self awaitExpectations];
-  [firestore shutdownWithCompletion:[self completionForExpectationWithName:@"Shutdown"]];
+  [firestore terminateWithCompletion:[self completionForExpectationWithName:@"Terminate"]];
   [self awaitExpectations];
 
   XCTAssertThrowsSpecific(
       {
         [firestore disableNetworkWithCompletion:^(NSError *error){
         }];
       },
-      NSException, @"The client has already been shutdown.");
+      NSException, @"The client has already been terminated.");
 }
 
 - (void)testMaintainsPersistenceAfterRestarting {
@@ -1251,9 +1251,9 @@ - (void)testMaintainsPersistenceAfterRestarting {
   NSDictionary<NSString *, id> *initialData = @{@"foo" : @"42"};
   [self writeDocumentRef:doc data:initialData];
 
-  // -clearPersistence() requires Firestore to be shut down. Shutdown FIRApp and remove the
+  // -clearPersistence() requires Firestore to be terminated. Shutdown FIRApp and remove the
   // firestore instance to emulate the way an end user would do this.
-  [self shutdownFirestore:firestore];
+  [self terminateFirestore:firestore];
   [self.firestores removeObject:firestore];
   [self deleteApp:app];
 
@@ -1278,9 +1278,9 @@ - (void)testCanClearPersistenceAfterRestarting {
   NSDictionary<NSString *, id> *initialData = @{@"foo" : @"42"};
   [self writeDocumentRef:doc data:initialData];
 
-  // -clearPersistence() requires Firestore to be shut down. Shutdown FIRApp and remove the
+  // -clearPersistence() requires Firestore to be terminated. Shutdown FIRApp and remove the
   // firestore instance to emulate the way an end user would do this.
-  [self shutdownFirestore:firestore];
+  [self terminateFirestore:firestore];
   [self.firestores removeObject:firestore];
   [firestore
       clearPersistenceWithCompletion:[self completionForExpectationWithName:@"Enable network"]];
@@ -1332,7 +1332,7 @@ - (void)testRestartFirestoreLeadsToNewInstance {
       @{@"owner" : @{@"name" : @"Jonny", @"email" : @"[email protected]"}};
   [self writeDocumentRef:[firestore documentWithPath:@"abc/123"] data:data];
 
-  [self shutdownFirestore:firestore];
+  [self terminateFirestore:firestore];
 
   // Create a new instance, check it's a different instance.
   FIRFirestore *newInstance = [FIRFirestore firestoreForApp:app];
@@ -1345,7 +1345,7 @@ - (void)testRestartFirestoreLeadsToNewInstance {
   XCTAssertTrue([data isEqualToDictionary:[snapshot data]]);
 }
 
-- (void)testAppDeleteLeadsToFirestoreShutdown {
+- (void)testAppDeleteLeadsToFirestoreTermination {
   FIRApp *app = testutil::AppForUnitTesting(util::MakeString([FSTIntegrationTestCase projectID]));
   FIRFirestore *firestore = [FIRFirestore firestoreForApp:app];
   firestore.settings = [FSTIntegrationTestCase settings];
@@ -1355,33 +1355,33 @@ - (void)testAppDeleteLeadsToFirestoreShutdown {
 
   [self deleteApp:app];
 
-  XCTAssertTrue(firestore.wrapped->client()->is_shutdown());
+  XCTAssertTrue(firestore.wrapped->client()->is_terminated());
 }
 
-- (void)testShutdownCanBeCalledMultipleTimes {
+- (void)testTerminateCanBeCalledMultipleTimes {
   FIRApp *app = testutil::AppForUnitTesting(util::MakeString([FSTIntegrationTestCase projectID]));
   FIRFirestore *firestore = [FIRFirestore firestoreForApp:app];
 
-  [firestore shutdownWithCompletion:[self completionForExpectationWithName:@"Shutdown1"]];
+  [firestore terminateWithCompletion:[self completionForExpectationWithName:@"Terminate1"]];
   [self awaitExpectations];
   XCTAssertThrowsSpecific(
       {
         [firestore disableNetworkWithCompletion:^(NSError *error){
         }];
       },
-      NSException, @"The client has already been shutdown.");
+      NSException, @"The client has already been terminated.");
 
-  [firestore shutdownWithCompletion:[self completionForExpectationWithName:@"Shutdown2"]];
+  [firestore terminateWithCompletion:[self completionForExpectationWithName:@"Terminate2"]];
   [self awaitExpectations];
   XCTAssertThrowsSpecific(
       {
         [firestore enableNetworkWithCompletion:^(NSError *error){
         }];
       },
-      NSException, @"The client has already been shutdown.");
+      NSException, @"The client has already been terminated.");
 }
 
-- (void)testCanRemoveListenerAfterShutdown {
+- (void)testCanRemoveListenerAfterTermination {
   FIRApp *app = testutil::AppForUnitTesting(util::MakeString([FSTIntegrationTestCase projectID]));
   FIRFirestore *firestore = [FIRFirestore firestoreForApp:app];
   firestore.settings = [FSTIntegrationTestCase settings];
@@ -1393,7 +1393,7 @@ - (void)testCanRemoveListenerAfterShutdown {
       [doc addSnapshotListener:[accumulator valueEventHandler]];
   [accumulator awaitEventWithName:@"Snapshot"];
 
-  [firestore shutdownWithCompletion:[self completionForExpectationWithName:@"shutdown"]];
+  [firestore terminateWithCompletion:[self completionForExpectationWithName:@"terminate"]];
   [self awaitExpectations];
 
   // This should proceed without error.

Firestore/Example/Tests/Util/FSTIntegrationTestCase.h

@@ -63,8 +63,8 @@ extern "C" {
  */
 - (FIRFirestore *)firestoreWithApp:(FIRApp *)app;
 
-/** Synchronously shuts down the given firestore. */
-- (void)shutdownFirestore:(FIRFirestore *)firestore;
+/** Synchronously terminates the given firestore. */
+- (void)terminateFirestore:(FIRFirestore *)firestore;
 
 /** Synchronously deletes the given FIRapp. */
 - (void)deleteApp:(FIRApp *)app;

Firestore/Example/Tests/Util/FSTIntegrationTestCase.mm

@@ -125,7 +125,7 @@ - (void)setUp {
 - (void)tearDown {
   @try {
     for (FIRFirestore *firestore in _firestores) {
-      [self shutdownFirestore:firestore];
+      [self terminateFirestore:firestore];
     }
   } @finally {
     _firestores = nil;
@@ -327,12 +327,12 @@ - (void)primeBackend {
 
     [listenerRegistration remove];
 
-    [self shutdownFirestore:db];
+    [self terminateFirestore:db];
   });
 }
 
-- (void)shutdownFirestore:(FIRFirestore *)firestore {
-  [firestore shutdownWithCompletion:[self completionForExpectationWithName:@"shutdown"]];
+- (void)terminateFirestore:(FIRFirestore *)firestore {
+  [firestore terminateWithCompletion:[self completionForExpectationWithName:@"shutdown"]];
   [self awaitExpectations];
 }
 

Firestore/Source/API/FIRFirestore+Internal.h

@@ -64,31 +64,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 + (FIRFirestore *)recoverFromFirestore:(std::shared_ptr<api::Firestore>)firestore;
 
-/**
- * Shuts down this `FIRFirestore` instance.
- *
- * After shutdown only the `clearPersistence` method may be used. Any other method
- * will throw an error.
- *
- * To restart after shutdown, simply create a new instance of FIRFirestore with
- * `firestore` or `firestoreForApp` methods.
- *
- * Shutdown does not cancel any pending writes and any tasks that are awaiting a response from
- * the server will not be resolved. The next time you start this instance, it will resume
- * attempting to send these writes to the server.
- *
- * Note: Under normal circumstances, calling this method is not required. This
- * method is useful only when you want to force this instance to release all of its resources or
- * in combination with `clearPersistence` to ensure that all local state is destroyed
- * between test runs.
- *
- * @param completion A block to execute once everything has shut down.
- */
-// TODO(b/135755126): Make this public.
-- (void)shutdownWithCompletion:(nullable void (^)(NSError *_Nullable error))completion
-    NS_SWIFT_NAME(shutdown(completion:));
-
-- (void)shutdownInternalWithCompletion:(nullable void (^)(NSError *_Nullable error))completion;
+- (void)terminateInternalWithCompletion:(nullable void (^)(NSError *_Nullable error))completion;
 
 - (const std::shared_ptr<util::AsyncQueue> &)workerQueue;
 

Firestore/Source/API/FIRFirestore.mm

@@ -281,6 +281,15 @@ - (void)waitForPendingWritesWithCompletion:(void (^)(NSError *_Nullable error))c
   _firestore->WaitForPendingWrites(util::MakeCallback(completion));
 }
 
+- (void)terminateWithCompletion:(nullable void (^)(NSError *_Nullable error))completion {
+  id<FSTFirestoreInstanceRegistry> strongRegistry = _registry;
+  if (strongRegistry) {
+    [strongRegistry
+        removeInstanceWithDatabase:util::MakeNSString(_firestore->database_id().database_id())];
+  }
+  [self terminateInternalWithCompletion:completion];
+}
+
 @end
 
 @implementation FIRFirestore (Internal)
@@ -305,17 +314,8 @@ + (FIRFirestore *)recoverFromFirestore:(std::shared_ptr<Firestore>)firestore {
   return (__bridge FIRFirestore *)firestore->extension();
 }
 
-- (void)shutdownInternalWithCompletion:(nullable void (^)(NSError *_Nullable error))completion {
-  _firestore->Shutdown(util::MakeCallback(completion));
-}
-
-- (void)shutdownWithCompletion:(nullable void (^)(NSError *_Nullable error))completion {
-  id<FSTFirestoreInstanceRegistry> strongRegistry = _registry;
-  if (strongRegistry) {
-    [strongRegistry
-        removeInstanceWithDatabase:util::MakeNSString(_firestore->database_id().database_id())];
-  }
-  [self shutdownInternalWithCompletion:completion];
+- (void)terminateInternalWithCompletion:(nullable void (^)(NSError *_Nullable error))completion {
+  _firestore->Terminate(util::MakeCallback(completion));
 }
 
 @end

Firestore/Source/API/FSTFirestoreComponent.mm

@@ -134,7 +134,7 @@ - (void)appWillBeDeleted:(FIRApp *)app {
     [_instances removeAllObjects];
   }
   for (NSString *key in instances) {
-    [instances[key] shutdownInternalWithCompletion:nil];
+    [instances[key] terminateInternalWithCompletion:nil];
   }
 }
 

Firestore/Source/Public/FIRFirestore.h

@@ -208,6 +208,31 @@ NS_SWIFT_NAME(Firestore)
  */
 - (void)waitForPendingWritesWithCompletion:(void (^)(NSError *_Nullable error))completion;
 
+#pragma mark - Terminating
+
+/**
+ * Terminates this `FIRFirestore` instance.
+ *
+ * After calling `terminate` only the `clearPersistence` method may be used. Any other method
+ * will throw an error.
+ *
+ * To restart after termination, simply create a new instance of FIRFirestore with
+ * `firestore` or `firestoreForApp` methods.
+ *
+ * Termination does not cancel any pending writes and any tasks that are awaiting a response from
+ * the server will not be resolved. The next time you start this instance, it will resume
+ * attempting to send these writes to the server.
+ *
+ * Note: Under normal circumstances, calling this method is not required. This
+ * method is useful only when you want to force this instance to release all of its resources or
+ * in combination with `clearPersistence` to ensure that all local state is destroyed
+ * between test runs.
+ *
+ * @param completion A block to execute once everything has been terminated.
+ */
+- (void)terminateWithCompletion:(nullable void (^)(NSError *_Nullable error))completion
+    NS_SWIFT_NAME(terminate(completion:));
+
 @end
 
 NS_ASSUME_NONNULL_END

Firestore/Swift/Tests/API/BasicCompileTests.swift

@@ -63,6 +63,10 @@ func main() {
   clearPersistence(database: db)
 
   types()
+
+  waitForPendingWrites(database: db)
+
+  terminateDb(database: db)
 }
 
 func initializeDb() -> Firestore {
@@ -448,3 +452,21 @@ func types() {
   let _: Transaction
   let _: WriteBatch
 }
+
+func waitForPendingWrites(database db: Firestore) {
+  db.waitForPendingWrites { error in
+    if let e = error {
+      print("Uh oh! \(e)")
+      return
+    }
+  }
+}
+
+func terminateDb(database db: Firestore) {
+  db.terminate { error in
+    if let e = error {
+      print("Uh oh! \(e)")
+      return
+    }
+  }
+}

Firestore/core/src/firebase/firestore/api/firestore.h

@@ -92,7 +92,7 @@ class Firestore : public std::enable_shared_from_this<Firestore> {
   void RunTransaction(core::TransactionUpdateCallback update_callback,
                       core::TransactionResultCallback result_callback);
 
-  void Shutdown(util::StatusCallback callback);
+  void Terminate(util::StatusCallback callback);
   void ClearPersistence(util::StatusCallback callback);
   void WaitForPendingWrites(util::StatusCallback callback);