1 /* 2 * 3 * Copyright 2015 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #import <Foundation/Foundation.h> 20 21 #import "GRXWriteable.h" 22 23 /** States of a writer. */ 24 typedef NS_ENUM(NSInteger, GRXWriterState) { 25 26 /** 27 * The writer has not yet been given a writeable to which it can push its values. To have a writer 28 * transition to the Started state, send it a startWithWriteable: message. 29 * 30 * A writer's state cannot be manually set to this value. 31 */ 32 GRXWriterStateNotStarted, 33 34 /** The writer might push values to the writeable at any moment. */ 35 GRXWriterStateStarted, 36 37 /** 38 * The writer is temporarily paused, and won't send any more values to the writeable unless its 39 * state is set back to Started. The writer might still transition to the Finished state at any 40 * moment, and is allowed to send writesFinishedWithError: to its writeable. 41 */ 42 GRXWriterStatePaused, 43 44 /** 45 * The writer has released its writeable and won't interact with it anymore. 46 * 47 * One seldomly wants to set a writer's state to this value, as its writeable isn't notified with 48 * a writesFinishedWithError: message. Instead, sending finishWithError: to the writer will make 49 * it notify the writeable and then transition to this state. 50 */ 51 GRXWriterStateFinished 52 }; 53 54 /** 55 * An GRXWriter object can produce, on demand, a sequence of values. The sequence may be produced 56 * asynchronously, and it may consist of any number of elements, including none or an infinite 57 * number. 58 * 59 * GRXWriter is the active dual of NSEnumerator. The difference between them is thus whether the 60 * object plays an active or passive role during usage: A user of NSEnumerator pulls values off it, 61 * and passes the values to a writeable. A user of GRXWriter, though, just gives it a writeable, and 62 * the GRXWriter instance pushes values to the writeable. This makes this protocol suitable to 63 * represent a sequence of future values, as well as collections with internal iteration. 64 * 65 * An instance of GRXWriter can start producing values after a writeable is passed to it. It can 66 * also be commanded to finish the sequence immediately (with an optional error). Finally, it can be 67 * asked to pause, and resumed later. All GRXWriter objects support pausing and early termination. 68 * 69 * Thread-safety: 70 * 71 * State transitions take immediate effect if the object is used from a single thread. Subclasses 72 * might offer stronger guarantees. 73 * 74 * Unless otherwise indicated by a conforming subclass, no messages should be sent concurrently to a 75 * GRXWriter. I.e., conforming classes aren't required to be thread-safe. 76 */ 77 @interface GRXWriter : NSObject 78 79 /** 80 * This property can be used to query the current state of the writer, which determines how it might 81 * currently use its writeable. Some state transitions can be triggered by setting this property to 82 * the corresponding value, and that's useful for advanced use cases like pausing an writer. For 83 * more details, see the documentation of the enum further down. 84 */ 85 @property(nonatomic) GRXWriterState state; 86 87 /** 88 * Transition to the Started state, and start sending messages to the writeable (a reference to it 89 * is retained). Messages to the writeable may be sent before the method returns, or they may be 90 * sent later in the future. See GRXWriteable.h for the different messages a writeable can receive. 91 * 92 * If this writer draws its values from an external source (e.g. from the filesystem or from a 93 * server), calling this method will commonly trigger side effects (like network connections). 94 * 95 * This method might only be called on writers in the NotStarted state. 96 */ 97 - (void)startWithWriteable:(id<GRXWriteable>)writeable; 98 99 /** 100 * Send writesFinishedWithError:errorOrNil to the writeable. Then release the reference to it and 101 * transition to the Finished state. 102 * 103 * This method might only be called on writers in the Started or Paused state. 104 */ 105 - (void)finishWithError:(NSError *)errorOrNil; 106 @end 107