ASTableView batch API and context object

AsyncDisplayKit/Details/ASBatchContext.h

@@ -0,0 +1,52 @@
+/* Copyright (c) 2014-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+/**
+ * @abstract A context object to notify when batch fetches are finished or cancelled.
+ */
+@interface ASBatchContext : NSObject
+
+/**
+ * Retreive the state of the current batch process.
+ *
+ * @returns A boolean reflecting if the owner of the context object is fetching another batch.
+ */
+- (BOOL)isFetching;
+
+/**
+ * Let the context object know that a batch fetch was completed.
+ *
+ * @param didComplete A boolean that states whether or not the batch fetch completed.
+ *
+ * @discussion Only by passing YES will the owner of the context know to attempt another batch update when necessary.
+ * For instance, when a table has reached the end of its data, a batch fetch will be attempted unless the context
+ * object thinks that it is still fetching.
+ */
+- (void)completeBatchFetching:(BOOL)didComplete;
+
+- (void)beginBatchFetching;
+
+/**
+ * Ask the context object if the batch fetching process was cancelled by the context owner.
+ *
+ * @discussion If an error occurs in the context owner, the batch fetching may become out of sync and need to be
+ * cancelled. For best practices, pass the return value of -batchWasCancelled to -completeBatchFetch:.
+ *
+ * @returns A boolean reflecting if the context object owner had to cancel the batch process.
+ */
+- (BOOL)batchFetchingWasCancelled;
+
+/**
+ * Notify the context object that something has interupted the batch fetching process.
+ *
+ * @discussion Call this method only when something has corrupted the batch fetching process. Calling this method should
+ * be left to the owner of the batch process unless there is a specific purpose.
+ */
+- (void)cancelBatchFetching;
+
+@end