Jorge Canizales | e8304d5 | 2015-02-17 19:50:51 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 3 | * Copyright 2015 gRPC authors. |
Jorge Canizales | e8304d5 | 2015-02-17 19:50:51 -0800 | [diff] [blame] | 4 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 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 |
Jorge Canizales | e8304d5 | 2015-02-17 19:50:51 -0800 | [diff] [blame] | 8 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
Jorge Canizales | e8304d5 | 2015-02-17 19:50:51 -0800 | [diff] [blame] | 10 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 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. |
Jorge Canizales | e8304d5 | 2015-02-17 19:50:51 -0800 | [diff] [blame] | 16 | * |
| 17 | */ |
| 18 | |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 19 | #import <Foundation/Foundation.h> |
| 20 | |
| 21 | #import "GRXWriteable.h" |
| 22 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 23 | /** States of a writer. */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 24 | typedef NS_ENUM(NSInteger, GRXWriterState) { |
| 25 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 32 | GRXWriterStateNotStarted, |
| 33 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 34 | /** The writer might push values to the writeable at any moment. */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 35 | GRXWriterStateStarted, |
| 36 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 42 | GRXWriterStatePaused, |
| 43 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 51 | GRXWriterStateFinished |
| 52 | }; |
| 53 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 7b52c98 | 2015-07-16 18:41:21 -0700 | [diff] [blame] | 77 | @interface GRXWriter : NSObject |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 78 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 85 | @property(nonatomic) GRXWriterState state; |
| 86 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 97 | - (void)startWithWriteable:(id<GRXWriteable>)writeable; |
| 98 | |
Jorge Canizales | b10776c | 2015-10-26 10:44:55 -0700 | [diff] [blame] | 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 | */ |
Jorge Canizales | 30697c9 | 2015-02-17 17:09:14 -0800 | [diff] [blame] | 105 | - (void)finishWithError:(NSError *)errorOrNil; |
| 106 | @end |