From 57e661510fc004912c3453438f0c0d918039ddc6 Mon Sep 17 00:00:00 2001 From: Morgan Chen Date: Thu, 30 Nov 2017 13:16:02 -0800 Subject: add completion execution guarantees to firestore write ops (#481) --- Firestore/Source/Public/FIRCollectionReference.h | 4 +++- Firestore/Source/Public/FIRDocumentReference.h | 23 ++++++++++++++++------- Firestore/Source/Public/FIRFirestore.h | 5 +++-- Firestore/Source/Public/FIRWriteBatch.h | 7 +++++-- 4 files changed, 27 insertions(+), 12 deletions(-) (limited to 'Firestore/Source/Public') diff --git a/Firestore/Source/Public/FIRCollectionReference.h b/Firestore/Source/Public/FIRCollectionReference.h index ba3389f..bc9a56a 100644 --- a/Firestore/Source/Public/FIRCollectionReference.h +++ b/Firestore/Source/Public/FIRCollectionReference.h @@ -81,7 +81,9 @@ NS_SWIFT_NAME(CollectionReference) * automatically. * * @param data An `NSDictionary` containing the data for the new document. - * @param completion A block to execute once the document has been successfully written. + * @param completion A block to execute once the document has been successfully written to + * the server. This block will not be called while the client is offline, though local + * changes will be visible immediately. * * @return A `FIRDocumentReference` pointing to the newly created document. */ diff --git a/Firestore/Source/Public/FIRDocumentReference.h b/Firestore/Source/Public/FIRDocumentReference.h index bd6d7b8..439e727 100644 --- a/Firestore/Source/Public/FIRDocumentReference.h +++ b/Firestore/Source/Public/FIRDocumentReference.h @@ -121,8 +121,10 @@ NS_SWIFT_NAME(DocumentReference) * is created. If a document already exists, it is overwritten. * * @param documentData An `NSDictionary` containing the fields that make up the document - * to be written. - * @param completion A block to execute once the document has been successfully written. + * to be written. + * @param completion A block to execute once the document has been successfully written to the + * server. This block will not be called while the client is offline, though local + * changes will be visible immediately. */ - (void)setData:(NSDictionary *)documentData completion:(nullable void (^)(NSError *_Nullable error))completion; @@ -135,7 +137,9 @@ NS_SWIFT_NAME(DocumentReference) * @param documentData An `NSDictionary` containing the fields that make up the document * to be written. * @param options A `FIRSetOptions` used to configure the set behavior. - * @param completion A block to execute once the document has been successfully written. + * @param completion A block to execute once the document has been successfully written to the + * server. This block will not be called while the client is offline, though local + * changes will be visible immediately. */ - (void)setData:(NSDictionary *)documentData options:(FIRSetOptions *)options @@ -146,7 +150,7 @@ NS_SWIFT_NAME(DocumentReference) * If the document does not exist, the update fails (specify a completion block to be notified). * * @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or - * `FIRFieldPath`) and values with which to update the document. + * `FIRFieldPath`) and values with which to update the document. */ - (void)updateData:(NSDictionary *)fields; @@ -155,9 +159,12 @@ NS_SWIFT_NAME(DocumentReference) * does not exist, the update fails and the specified completion block receives an error. * * @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or - * `FIRFieldPath`) and values with which to update the document. + * `FIRFieldPath`) and values with which to update the document. * @param completion A block to execute when the update is complete. If the update is successful the - * error parameter will be nil, otherwise it will give an indication of how the update failed. + * error parameter will be nil, otherwise it will give an indication of how the update failed. + * This block will only execute when the client is online and the commit has completed against + * the server. The completion handler will not be called when the device is offline, though + * local changes will be visible immediately. */ - (void)updateData:(NSDictionary *)fields completion:(nullable void (^)(NSError *_Nullable error))completion; @@ -171,7 +178,9 @@ NS_SWIFT_NAME(DocumentReference) /** * Deletes the document referred to by this `FIRDocumentReference`. * - * @param completion A block to execute once the document has been successfully deleted. + * @param completion A block to execute once the document has been successfully written to the + * server. This block will not be called while the client is offline, though local + * changes will be visible immediately. */ // clang-format off - (void)deleteDocumentWithCompletion:(nullable void (^)(NSError *_Nullable error))completion diff --git a/Firestore/Source/Public/FIRFirestore.h b/Firestore/Source/Public/FIRFirestore.h index 0935917..91a96a5 100644 --- a/Firestore/Source/Public/FIRFirestore.h +++ b/Firestore/Source/Public/FIRFirestore.h @@ -115,10 +115,11 @@ NS_SWIFT_NAME(Firestore) * and collections. Unlike other firestore access, data accessed with the transaction will not * reflect local changes that have not been committed. For this reason, it is required that all * reads are performed before any writes. Transactions must be performed while online. Otherwise, - * reads will fail, and the final commit will fail. + * reads will fail, the final commit will fail, and the completion block will return an error. * * @param updateBlock The block to execute within the transaction context. - * @param completion The block to call with the result or error of the transaction. + * @param completion The block to call with the result or error of the transaction. This + * block will run even if the client is offline, unless the process is killed. */ - (void)runTransactionWithBlock:(id _Nullable (^)(FIRTransaction *, NSError **))updateBlock completion:(void (^)(id _Nullable result, NSError *_Nullable error))completion; diff --git a/Firestore/Source/Public/FIRWriteBatch.h b/Firestore/Source/Public/FIRWriteBatch.h index a74d451..5f0034c 100644 --- a/Firestore/Source/Public/FIRWriteBatch.h +++ b/Firestore/Source/Public/FIRWriteBatch.h @@ -73,7 +73,7 @@ NS_SWIFT_NAME(WriteBatch) * If document does not exist, the write batch will fail. * * @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or - * `FIRFieldPath`) and values with which to update the document. + * `FIRFieldPath`) and values with which to update the document. * @param document A reference to the document whose data should be updated. * @return This `FIRWriteBatch` instance. Used for chaining method calls. */ @@ -96,7 +96,10 @@ NS_SWIFT_NAME(WriteBatch) * Commits all of the writes in this write batch as a single atomic unit. * * @param completion A block to be called once all of the writes in the batch have been - * successfully written to the backend as an atomic unit. + * successfully written to the backend as an atomic unit. This block will only execute + * when the client is online and the commit has completed against the server. The + * completion handler will not be called when the device is offline, though local + * changes will be visible immediately. */ - (void)commitWithCompletion:(void (^)(NSError *_Nullable error))completion; -- cgit v1.2.3