Reformat comments as Cocoadocs

pull/3961/head
Jorge Canizales 9 years ago
parent bbb7774b83
commit b10776c509
  1. 28
      src/objective-c/GRPCClient/GRPCCall+Tests.h
  2. 2
      src/objective-c/GRPCClient/GRPCCall.h
  3. 12
      src/objective-c/GRPCClient/private/GRPCChannel.h
  4. 20
      src/objective-c/GRPCClient/private/GRPCCompletionQueue.h
  5. 6
      src/objective-c/GRPCClient/private/GRPCHost.h
  6. 8
      src/objective-c/GRPCClient/private/GRPCSecureChannel.h
  7. 2
      src/objective-c/GRPCClient/private/GRPCWrappedCall.h
  8. 6
      src/objective-c/GRPCClient/private/NSError+GRPC.h
  9. 6
      src/objective-c/ProtoRPC/ProtoMethod.h
  10. 36
      src/objective-c/RxLibrary/GRXBufferedPipe.h
  11. 54
      src/objective-c/RxLibrary/GRXConcurrentWriteable.h
  12. 24
      src/objective-c/RxLibrary/GRXForwardingWriter.h
  13. 70
      src/objective-c/RxLibrary/GRXImmediateWriter.h
  14. 22
      src/objective-c/RxLibrary/GRXWriteable.h
  15. 44
      src/objective-c/RxLibrary/GRXWriter+Immediate.h
  16. 6
      src/objective-c/RxLibrary/GRXWriter+Transformations.h
  17. 116
      src/objective-c/RxLibrary/GRXWriter.h
  18. 22
      src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h
  19. 12
      src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h
  20. 14
      src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h
  21. 8
      src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h
  22. 2
      src/objective-c/RxLibrary/transformations/GRXMappingWriter.h

@ -33,22 +33,28 @@
#import "GRPCCall.h"
// Methods to let tune down the security of gRPC connections for specific hosts. These shouldn't be
// used in releases, but are sometimes needed for testing.
/**
* Methods to let tune down the security of gRPC connections for specific hosts. These shouldn't be
* used in releases, but are sometimes needed for testing.
*/
@interface GRPCCall (Tests)
// Establish all SSL connections to the provided host using the passed SSL target name and the root
// certificates found in the file at |certsPath|.
//
// Must be called before any gRPC call to that host is made. It's illegal to pass the same host to
// more than one invocation of the methods of this category.
/**
* Establish all SSL connections to the provided host using the passed SSL target name and the root
* certificates found in the file at |certsPath|.
*
* Must be called before any gRPC call to that host is made. It's illegal to pass the same host to
* more than one invocation of the methods of this category.
*/
+ (void)useTestCertsPath:(NSString *)certsPath
testName:(NSString *)testName
forHost:(NSString *)host;
// Establish all connections to the provided host using cleartext instead of SSL.
//
// Must be called before any gRPC call to that host is made. It's illegal to pass the same host to
// more than one invocation of the methods of this category.
/**
* Establish all connections to the provided host using cleartext instead of SSL.
*
* Must be called before any gRPC call to that host is made. It's illegal to pass the same host to
* more than one invocation of the methods of this category.
*/
+ (void)useInsecureConnectionsForHost:(NSString *)host;
@end

@ -61,7 +61,7 @@ extern NSString *const kGRPCErrorDomain;
* server applications to produce.
*/
typedef NS_ENUM(NSUInteger, GRPCErrorCode) {
// The operation was cancelled (typically by the caller).
/** The operation was cancelled (typically by the caller). */
GRPCErrorCodeCancelled = 1,
/**

@ -35,12 +35,16 @@
struct grpc_channel;
// Each separate instance of this class represents at least one TCP connection to the provided host.
// Create them using one of the subclasses |GRPCSecureChannel| and |GRPCUnsecuredChannel|.
/**
* Each separate instance of this class represents at least one TCP connection to the provided host.
* Create them using one of the subclasses |GRPCSecureChannel| and |GRPCUnsecuredChannel|.
*/
@interface GRPCChannel : NSObject
@property(nonatomic, readonly) struct grpc_channel *unmanagedChannel;
// This initializer takes ownership of the passed channel, and will destroy it when this object is
// deallocated. It's illegal to pass the same grpc_channel to two different GRPCChannel objects.
/**
* This initializer takes ownership of the passed channel, and will destroy it when this object is
* deallocated. It's illegal to pass the same grpc_channel to two different GRPCChannel objects.
*/
- (instancetype)initWithChannel:(struct grpc_channel *)unmanagedChannel NS_DESIGNATED_INITIALIZER;
@end

@ -36,15 +36,17 @@
typedef void(^GRPCQueueCompletionHandler)(bool success);
// This class lets one more easily use |grpc_completion_queue|. To use it, pass the value of the
// |unmanagedQueue| property of an instance of this class to |grpc_channel_create_call|. Then for
// every |grpc_call_*| method that accepts a tag, you can pass a block of type
// |GRPCQueueCompletionHandler| (remembering to cast it using |__bridge_retained|). The block is
// guaranteed to eventually be called, by a concurrent queue, and then released. Each such block is
// passed a |bool| that tells if the operation was successful.
//
// Release the GRPCCompletionQueue object only after you are not going to pass any more blocks to
// the |grpc_call| that's using it.
/**
* This class lets one more easily use |grpc_completion_queue|. To use it, pass the value of the
* |unmanagedQueue| property of an instance of this class to |grpc_channel_create_call|. Then for
* every |grpc_call_*| method that accepts a tag, you can pass a block of type
* |GRPCQueueCompletionHandler| (remembering to cast it using |__bridge_retained|). The block is
* guaranteed to eventually be called, by a concurrent queue, and then released. Each such block is
* passed a |bool| that tells if the operation was successful.
*
* Release the GRPCCompletionQueue object only after you are not going to pass any more blocks to
* the |grpc_call| that's using it.
*/
@interface GRPCCompletionQueue : NSObject
@property(nonatomic, readonly) grpc_completion_queue *unmanagedQueue;

@ -40,18 +40,18 @@ struct grpc_call;
@property(nonatomic, readonly) NSString *address;
// The following properties should only be modified for testing:
/** The following properties should only be modified for testing: */
@property(nonatomic, getter=isSecure) BOOL secure;
@property(nonatomic, copy) NSString *pathToCertificates;
@property(nonatomic, copy) NSString *hostNameOverride;
// Host objects initialized with the same address are the same.
/** Host objects initialized with the same address are the same. */
+ (instancetype)hostWithAddress:(NSString *)address;
- (instancetype)initWithAddress:(NSString *)address NS_DESIGNATED_INITIALIZER;
// Create a grpc_call object to the provided path on this host.
/** Create a grpc_call object to the provided path on this host. */
- (struct grpc_call *)unmanagedCallWithPath:(NSString *)path
completionQueue:(GRPCCompletionQueue *)queue;

@ -40,13 +40,15 @@ struct grpc_credentials;
@interface GRPCSecureChannel : GRPCChannel
- (instancetype)initWithHost:(NSString *)host;
// Only in tests shouldn't pathToCertificates or hostNameOverride be nil. Passing nil for
// pathToCertificates results in using the default root certificates distributed with the library.
/**
* Only in tests shouldn't pathToCertificates or hostNameOverride be nil. Passing nil for
* pathToCertificates results in using the default root certificates distributed with the library.
*/
- (instancetype)initWithHost:(NSString *)host
pathToCertificates:(NSString *)path
hostNameOverride:(NSString *)hostNameOverride;
// The passed arguments aren't required to be valid beyond the invocation of this initializer.
/** The passed arguments aren't required to be valid beyond the invocation of this initializer. */
- (instancetype)initWithHost:(NSString *)host
credentials:(struct grpc_credentials *)credentials
args:(grpc_channel_args *)args NS_DESIGNATED_INITIALIZER;

@ -39,7 +39,7 @@
@interface GRPCOperation : NSObject
@property(nonatomic, readonly) grpc_op op;
// Guaranteed to be called when the operation has finished.
/** Guaranteed to be called when the operation has finished. */
- (void)finish;
@end

@ -35,7 +35,9 @@
#include <grpc/grpc.h>
@interface NSError (GRPC)
// Returns nil if the status code is OK. Otherwise, a NSError whose code is one of |GRPCErrorCode|
// and whose domain is |kGRPCErrorDomain|.
/**
* Returns nil if the status code is OK. Otherwise, a NSError whose code is one of |GRPCErrorCode|
* and whose domain is |kGRPCErrorDomain|.
*/
+ (instancetype)grpc_errorFromStatusCode:(grpc_status_code)statusCode details:(char *)details;
@end

@ -33,8 +33,10 @@
#import <Foundation/Foundation.h>
// A fully-qualified proto service method name. Full qualification is needed because a gRPC endpoint
// can implement multiple services.
/**
* A fully-qualified proto service method name. Full qualification is needed because a gRPC endpoint
* can implement multiple services.
*/
@interface ProtoMethod : NSObject
@property(nonatomic, readonly) NSString *package;
@property(nonatomic, readonly) NSString *service;

@ -36,25 +36,27 @@
#import "GRXWriteable.h"
#import "GRXWriter.h"
// A buffered pipe is a Writer that also acts as a Writeable.
// Once it is started, whatever values are written into it (via -writeValue:) will be propagated
// immediately, unless flow control prevents it.
// If it is throttled and keeps receiving values, as well as if it receives values before being
// started, it will buffer them and propagate them in order as soon as its state becomes Started.
// If it receives an error (via -writesFinishedWithError:), it will drop any buffered values and
// propagate the error immediately.
//
// Beware that a pipe of this type can't prevent receiving more values when it is paused (for
// example if used to write data to a congested network connection). Because in such situations the
// pipe will keep buffering all data written to it, your application could run out of memory and
// crash. If you want to react to flow control signals to prevent that, instead of using this class
// you can implement an object that conforms to GRXWriter.
//
// Thread-safety:
// The methods of an object of this class should not be called concurrently from different threads.
/**
* A buffered pipe is a Writer that also acts as a Writeable.
* Once it is started, whatever values are written into it (via -writeValue:) will be propagated
* immediately, unless flow control prevents it.
* If it is throttled and keeps receiving values, as well as if it receives values before being
* started, it will buffer them and propagate them in order as soon as its state becomes Started.
* If it receives an error (via -writesFinishedWithError:), it will drop any buffered values and
* propagate the error immediately.
*
* Beware that a pipe of this type can't prevent receiving more values when it is paused (for
* example if used to write data to a congested network connection). Because in such situations the
* pipe will keep buffering all data written to it, your application could run out of memory and
* crash. If you want to react to flow control signals to prevent that, instead of using this class
* you can implement an object that conforms to GRXWriter.
*
* Thread-safety:
* The methods of an object of this class should not be called concurrently from different threads.
*/
@interface GRXBufferedPipe : GRXWriter<GRXWriteable>
// Convenience constructor.
/** Convenience constructor. */
+ (instancetype)pipe;
@end

@ -36,36 +36,48 @@
#import "GRXWriter.h"
#import "GRXWriteable.h"
// This is a thread-safe wrapper over a GRXWriteable instance. It lets one enqueue calls to a
// GRXWriteable instance for the main thread, guaranteeing that writesFinishedWithError: is the last
// message sent to it (no matter what messages are sent to the wrapper, in what order, nor from
// which thread). It also guarantees that, if cancelWithError: is called from the main thread (e.g.
// by the app cancelling the writes), no further messages are sent to the writeable except
// writesFinishedWithError:.
//
// TODO(jcanizales): Let the user specify another queue for the writeable callbacks.
/**
* This is a thread-safe wrapper over a GRXWriteable instance. It lets one enqueue calls to a
* GRXWriteable instance for the main thread, guaranteeing that writesFinishedWithError: is the last
* message sent to it (no matter what messages are sent to the wrapper, in what order, nor from
* which thread). It also guarantees that, if cancelWithError: is called from the main thread (e.g.
* by the app cancelling the writes), no further messages are sent to the writeable except
* writesFinishedWithError:.
*
* TODO(jcanizales): Let the user specify another queue for the writeable callbacks.
*/
@interface GRXConcurrentWriteable : NSObject
// The GRXWriteable passed is the wrapped writeable.
// The GRXWriteable instance is retained until writesFinishedWithError: is sent to it, and released
// after that.
/**
* The GRXWriteable passed is the wrapped writeable.
* The GRXWriteable instance is retained until writesFinishedWithError: is sent to it, and released
* after that.
*/
- (instancetype)initWithWriteable:(id<GRXWriteable>)writeable NS_DESIGNATED_INITIALIZER;
// Enqueues writeValue: to be sent to the writeable in the main thread.
// The passed handler is invoked from the main thread after writeValue: returns.
/**
* Enqueues writeValue: to be sent to the writeable in the main thread.
* The passed handler is invoked from the main thread after writeValue: returns.
*/
- (void)enqueueValue:(id)value completionHandler:(void (^)())handler;
// Enqueues writesFinishedWithError:nil to be sent to the writeable in the main thread. After that
// message is sent to the writeable, all other methods of this object are effectively noops.
/**
* Enqueues writesFinishedWithError:nil to be sent to the writeable in the main thread. After that
* message is sent to the writeable, all other methods of this object are effectively noops.
*/
- (void)enqueueSuccessfulCompletion;
// If the writeable has not yet received a writesFinishedWithError: message, this will enqueue one
// to be sent to it in the main thread, and cancel all other pending messages to the writeable
// enqueued by this object (both past and future).
// The error argument cannot be nil.
/**
* If the writeable has not yet received a writesFinishedWithError: message, this will enqueue one
* to be sent to it in the main thread, and cancel all other pending messages to the writeable
* enqueued by this object (both past and future).
* The error argument cannot be nil.
*/
- (void)cancelWithError:(NSError *)error;
// Cancels all pending messages to the writeable enqueued by this object (both past and future).
// Because the writeable won't receive writesFinishedWithError:, this also releases the writeable.
/**
* Cancels all pending messages to the writeable enqueued by this object (both past and future).
* Because the writeable won't receive writesFinishedWithError:, this also releases the writeable.
*/
- (void)cancelSilently;
@end

@ -33,17 +33,19 @@
#import "GRXWriter.h"
// A "proxy" class that simply forwards values, completion, and errors from its input writer to its
// writeable.
// It is useful as a superclass for pipes that act as a transformation of their
// input writer, and for classes that represent objects with input and
// output sequences of values, like an RPC.
//
// Thread-safety:
// All messages sent to this object need to be serialized. When it is started, the writer it wraps
// is started in the same thread. Manual state changes are propagated to the wrapped writer in the
// same thread too. Importantly, all messages the wrapped writer sends to its writeable need to be
// serialized with any message sent to this object.
/**
* A "proxy" class that simply forwards values, completion, and errors from its input writer to its
* writeable.
* It is useful as a superclass for pipes that act as a transformation of their
* input writer, and for classes that represent objects with input and
* output sequences of values, like an RPC.
*
* Thread-safety:
* All messages sent to this object need to be serialized. When it is started, the writer it wraps
* is started in the same thread. Manual state changes are propagated to the wrapped writer in the
* same thread too. Importantly, all messages the wrapped writer sends to its writeable need to be
* serialized with any message sent to this object.
*/
@interface GRXForwardingWriter : GRXWriter
- (instancetype)initWithWriter:(GRXWriter *)writer NS_DESIGNATED_INITIALIZER;
@end

@ -35,46 +35,60 @@
#import "GRXWriter.h"
// Utility to construct GRXWriter instances from values that are immediately available when
// required.
//
// Thread-safety:
//
// An object of this class shouldn't be messaged concurrently by more than one thread. It will start
// messaging the writeable before |startWithWriteable:| returns, in the same thread. That is the
// only place where the writer can be paused or stopped prematurely.
//
// If a paused writer of this class is resumed, it will start messaging the writeable, in the same
// thread, before |setState:| returns. Because the object can't be legally accessed concurrently,
// that's the only place where it can be paused again (or stopped).
/**
* Utility to construct GRXWriter instances from values that are immediately available when
* required.
*
* Thread-safety:
*
* An object of this class shouldn't be messaged concurrently by more than one thread. It will start
* messaging the writeable before |startWithWriteable:| returns, in the same thread. That is the
* only place where the writer can be paused or stopped prematurely.
*
* If a paused writer of this class is resumed, it will start messaging the writeable, in the same
* thread, before |setState:| returns. Because the object can't be legally accessed concurrently,
* that's the only place where it can be paused again (or stopped).
*/
@interface GRXImmediateWriter : GRXWriter
// Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to
// its writeable. The NSEnumerator is released when it finishes.
/**
* Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to
* its writeable. The NSEnumerator is released when it finishes.
*/
+ (GRXWriter *)writerWithEnumerator:(NSEnumerator *)enumerator;
// Returns a writer that pushes to its writeable the successive values returned by the passed
// block. When the block first returns nil, it is released.
/**
* Returns a writer that pushes to its writeable the successive values returned by the passed
* block. When the block first returns nil, it is released.
*/
+ (GRXWriter *)writerWithValueSupplier:(id (^)())block;
// Returns a writer that iterates over the values of the passed container and pushes them to
// its writeable. The container is released when the iteration is over.
//
// Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to
// call one method per element. Because GRXWriteable instances accept values one by one, that speed
// gain doesn't happen here.
/**
* Returns a writer that iterates over the values of the passed container and pushes them to
* its writeable. The container is released when the iteration is over.
*
* Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to
* call one method per element. Because GRXWriteable instances accept values one by one, that speed
* gain doesn't happen here.
*/
+ (GRXWriter *)writerWithContainer:(id<NSFastEnumeration>)container;
// Returns a writer that sends the passed value to its writeable and then finishes (releasing the
// value).
/**
* Returns a writer that sends the passed value to its writeable and then finishes (releasing the
* value).
*/
+ (GRXWriter *)writerWithValue:(id)value;
// Returns a writer that, as part of its start method, sends the passed error to the writeable
// (then releasing the error).
/**
* Returns a writer that, as part of its start method, sends the passed error to the writeable
* (then releasing the error).
*/
+ (GRXWriter *)writerWithError:(NSError *)error;
// Returns a writer that, as part of its start method, finishes immediately without sending any
// values to its writeable.
/**
* Returns a writer that, as part of its start method, finishes immediately without sending any
* values to its writeable.
*/
+ (GRXWriter *)emptyWriter;
@end

@ -33,16 +33,20 @@
#import <Foundation/Foundation.h>
// A GRXWriteable is an object to which a sequence of values can be sent. The
// sequence finishes with an optional error.
/**
* A GRXWriteable is an object to which a sequence of values can be sent. The
* sequence finishes with an optional error.
*/
@protocol GRXWriteable <NSObject>
// Push the next value of the sequence to the receiving object.
/** Push the next value of the sequence to the receiving object. */
- (void)writeValue:(id)value;
// Signal that the sequence is completed, or that an error ocurred. After this
// message is sent to the instance, neither it nor writeValue: may be
// called again.
/**
* Signal that the sequence is completed, or that an error ocurred. After this
* message is sent to the instance, neither it nor writeValue: may be
* called again.
*/
- (void)writesFinishedWithError:(NSError *)errorOrNil;
@end
@ -51,8 +55,10 @@ typedef void (^GRXCompletionHandler)(NSError *errorOrNil);
typedef void (^GRXSingleHandler)(id value, NSError *errorOrNil);
typedef void (^GRXEventHandler)(BOOL done, id value, NSError *error);
// Utility to create objects that conform to the GRXWriteable protocol, from
// blocks that handle each of the two methods of the protocol.
/**
* Utility to create objects that conform to the GRXWriteable protocol, from
* blocks that handle each of the two methods of the protocol.
*/
@interface GRXWriteable : NSObject<GRXWriteable>
+ (instancetype)writeableWithSingleHandler:(GRXSingleHandler)handler;

@ -35,32 +35,44 @@
@interface GRXWriter (Immediate)
// Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to
// its writeable. The NSEnumerator is released when it finishes.
/**
* Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to
* its writeable. The NSEnumerator is released when it finishes.
*/
+ (instancetype)writerWithEnumerator:(NSEnumerator *)enumerator;
// Returns a writer that pushes to its writeable the successive values returned by the passed
// block. When the block first returns nil, it is released.
/**
* Returns a writer that pushes to its writeable the successive values returned by the passed
* block. When the block first returns nil, it is released.
*/
+ (instancetype)writerWithValueSupplier:(id (^)())block;
// Returns a writer that iterates over the values of the passed container and pushes them to
// its writeable. The container is released when the iteration is over.
//
// Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to
// call one method per element. Because GRXWriteable instances accept values one by one, that speed
// gain doesn't happen here.
/**
* Returns a writer that iterates over the values of the passed container and pushes them to
* its writeable. The container is released when the iteration is over.
*
* Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to
* call one method per element. Because GRXWriteable instances accept values one by one, that speed
* gain doesn't happen here.
*/
+ (instancetype)writerWithContainer:(id<NSFastEnumeration>)container;
// Returns a writer that sends the passed value to its writeable and then finishes (releasing the
// value).
/**
* Returns a writer that sends the passed value to its writeable and then finishes (releasing the
* value).
*/
+ (instancetype)writerWithValue:(id)value;
// Returns a writer that, as part of its start method, sends the passed error to the writeable
// (then releasing the error).
/**
* Returns a writer that, as part of its start method, sends the passed error to the writeable
* (then releasing the error).
*/
+ (instancetype)writerWithError:(NSError *)error;
// Returns a writer that, as part of its start method, finishes immediately without sending any
// values to its writeable.
/**
* Returns a writer that, as part of its start method, finishes immediately without sending any
* values to its writeable.
*/
+ (instancetype)emptyWriter;
@end

@ -35,8 +35,10 @@
@interface GRXWriter (Transformations)
// Returns a writer that wraps the receiver, and has all the values the receiver would write
// transformed by the provided mapping function.
/**
* Returns a writer that wraps the receiver, and has all the values the receiver would write
* transformed by the provided mapping function.
*/
- (GRXWriter *)map:(id (^)(id value))map;
@end

@ -35,73 +35,87 @@
#import "GRXWriteable.h"
// States of a writer.
/** States of a writer. */
typedef NS_ENUM(NSInteger, GRXWriterState) {
// The writer has not yet been given a writeable to which it can push its values. To have a writer
// transition to the Started state, send it a startWithWriteable: message.
//
// A writer's state cannot be manually set to this value.
/**
* The writer has not yet been given a writeable to which it can push its values. To have a writer
* transition to the Started state, send it a startWithWriteable: message.
*
* A writer's state cannot be manually set to this value.
*/
GRXWriterStateNotStarted,
// The writer might push values to the writeable at any moment.
/** The writer might push values to the writeable at any moment. */
GRXWriterStateStarted,
// The writer is temporarily paused, and won't send any more values to the writeable unless its
// state is set back to Started. The writer might still transition to the Finished state at any
// moment, and is allowed to send writesFinishedWithError: to its writeable.
/**
* The writer is temporarily paused, and won't send any more values to the writeable unless its
* state is set back to Started. The writer might still transition to the Finished state at any
* moment, and is allowed to send writesFinishedWithError: to its writeable.
*/
GRXWriterStatePaused,
// The writer has released its writeable and won't interact with it anymore.
//
// One seldomly wants to set a writer's state to this value, as its writeable isn't notified with
// a writesFinishedWithError: message. Instead, sending finishWithError: to the writer will make
// it notify the writeable and then transition to this state.
/**
* The writer has released its writeable and won't interact with it anymore.
*
* One seldomly wants to set a writer's state to this value, as its writeable isn't notified with
* a writesFinishedWithError: message. Instead, sending finishWithError: to the writer will make
* it notify the writeable and then transition to this state.
*/
GRXWriterStateFinished
};
// An GRXWriter object can produce, on demand, a sequence of values. The sequence may be produced
// asynchronously, and it may consist of any number of elements, including none or an infinite
// number.
//
// GRXWriter is the active dual of NSEnumerator. The difference between them is thus whether the
// object plays an active or passive role during usage: A user of NSEnumerator pulls values off it,
// and passes the values to a writeable. A user of GRXWriter, though, just gives it a writeable, and
// the GRXWriter instance pushes values to the writeable. This makes this protocol suitable to
// represent a sequence of future values, as well as collections with internal iteration.
//
// An instance of GRXWriter can start producing values after a writeable is passed to it. It can
// also be commanded to finish the sequence immediately (with an optional error). Finally, it can be
// asked to pause, and resumed later. All GRXWriter objects support pausing and early termination.
//
// Thread-safety:
//
// State transitions take immediate effect if the object is used from a single thread. Subclasses
// might offer stronger guarantees.
//
// Unless otherwise indicated by a conforming subclass, no messages should be sent concurrently to a
// GRXWriter. I.e., conforming classes aren't required to be thread-safe.
/**
* An GRXWriter object can produce, on demand, a sequence of values. The sequence may be produced
* asynchronously, and it may consist of any number of elements, including none or an infinite
* number.
*
* GRXWriter is the active dual of NSEnumerator. The difference between them is thus whether the
* object plays an active or passive role during usage: A user of NSEnumerator pulls values off it,
* and passes the values to a writeable. A user of GRXWriter, though, just gives it a writeable, and
* the GRXWriter instance pushes values to the writeable. This makes this protocol suitable to
* represent a sequence of future values, as well as collections with internal iteration.
*
* An instance of GRXWriter can start producing values after a writeable is passed to it. It can
* also be commanded to finish the sequence immediately (with an optional error). Finally, it can be
* asked to pause, and resumed later. All GRXWriter objects support pausing and early termination.
*
* Thread-safety:
*
* State transitions take immediate effect if the object is used from a single thread. Subclasses
* might offer stronger guarantees.
*
* Unless otherwise indicated by a conforming subclass, no messages should be sent concurrently to a
* GRXWriter. I.e., conforming classes aren't required to be thread-safe.
*/
@interface GRXWriter : NSObject
// This property can be used to query the current state of the writer, which determines how it might
// currently use its writeable. Some state transitions can be triggered by setting this property to
// the corresponding value, and that's useful for advanced use cases like pausing an writer. For
// more details, see the documentation of the enum further down.
/**
* This property can be used to query the current state of the writer, which determines how it might
* currently use its writeable. Some state transitions can be triggered by setting this property to
* the corresponding value, and that's useful for advanced use cases like pausing an writer. For
* more details, see the documentation of the enum further down.
*/
@property(nonatomic) GRXWriterState state;
// Transition to the Started state, and start sending messages to the writeable (a reference to it
// is retained). Messages to the writeable may be sent before the method returns, or they may be
// sent later in the future. See GRXWriteable.h for the different messages a writeable can receive.
//
// If this writer draws its values from an external source (e.g. from the filesystem or from a
// server), calling this method will commonly trigger side effects (like network connections).
//
// This method might only be called on writers in the NotStarted state.
/**
* Transition to the Started state, and start sending messages to the writeable (a reference to it
* is retained). Messages to the writeable may be sent before the method returns, or they may be
* sent later in the future. See GRXWriteable.h for the different messages a writeable can receive.
*
* If this writer draws its values from an external source (e.g. from the filesystem or from a
* server), calling this method will commonly trigger side effects (like network connections).
*
* This method might only be called on writers in the NotStarted state.
*/
- (void)startWithWriteable:(id<GRXWriteable>)writeable;
// Send writesFinishedWithError:errorOrNil to the writeable. Then release the reference to it and
// transition to the Finished state.
//
// This method might only be called on writers in the Started or Paused state.
/**
* Send writesFinishedWithError:errorOrNil to the writeable. Then release the reference to it and
* transition to the Finished state.
*
* This method might only be called on writers in the Started or Paused state.
*/
- (void)finishWithError:(NSError *)errorOrNil;
@end

@ -35,17 +35,23 @@
@interface NSEnumerator (GRXUtil)
// Returns a NSEnumerator instance that iterates through the elements of the passed container that
// supports fast enumeration. Note that this negates the speed benefits of fast enumeration over
// NSEnumerator. It's only intended for the rare cases when one needs the latter and only has the
// former, e.g. for iteration that needs to be paused and resumed later.
/**
* Returns a NSEnumerator instance that iterates through the elements of the passed container that
* supports fast enumeration. Note that this negates the speed benefits of fast enumeration over
* NSEnumerator. It's only intended for the rare cases when one needs the latter and only has the
* former, e.g. for iteration that needs to be paused and resumed later.
*/
+ (NSEnumerator *)grx_enumeratorWithContainer:(id<NSFastEnumeration>)container;
// Returns a NSEnumerator instance that provides a single object before finishing. The value is then
// released.
/**
* Returns a NSEnumerator instance that provides a single object before finishing. The value is then
* released.
*/
+ (NSEnumerator *)grx_enumeratorWithSingleValue:(id)value;
// Returns a NSEnumerator instance that delegates the invocations of nextObject to the passed block.
// When the block first returns nil, it is released.
/**
* Returns a NSEnumerator instance that delegates the invocations of nextObject to the passed block.
* When the block first returns nil, it is released.
*/
+ (NSEnumerator *)grx_enumeratorWithValueSupplier:(id (^)())block;
@end

@ -33,10 +33,14 @@
#import <Foundation/Foundation.h>
// Concrete subclass of NSEnumerator that delegates the invocations of nextObject to a block passed
// on initialization.
/**
* Concrete subclass of NSEnumerator that delegates the invocations of nextObject to a block passed
* on initialization.
*/
@interface GRXNSBlockEnumerator : NSEnumerator
// The first time the passed block returns nil, the enumeration will end and the block will be
// released.
/**
* The first time the passed block returns nil, the enumeration will end and the block will be
* released.
*/
- (instancetype)initWithValueSupplier:(id (^)())block;
@end

@ -33,11 +33,15 @@
#import <Foundation/Foundation.h>
// This is a bridge to interact through NSEnumerator's interface with objects that only conform to
// NSFastEnumeration. (There's nothing specifically fast about it - you certainly don't win any
// speed by using this instead of a NSEnumerator provided by your container).
/**
* This is a bridge to interact through NSEnumerator's interface with objects that only conform to
* NSFastEnumeration. (There's nothing specifically fast about it - you certainly don't win any
* speed by using this instead of a NSEnumerator provided by your container).
*/
@interface GRXNSFastEnumerator : NSEnumerator
// After the iteration of the container (via the NSFastEnumeration protocol) is over, the container
// is released. If the container is modified during enumeration, an exception is thrown.
/**
* After the iteration of the container (via the NSFastEnumeration protocol) is over, the container
* is released. If the container is modified during enumeration, an exception is thrown.
*/
- (instancetype)initWithContainer:(id<NSFastEnumeration>)container;
@end

@ -33,9 +33,11 @@
#import <Foundation/Foundation.h>
// Concrete subclass of NSEnumerator whose instances return a single object before finishing.
/** Concrete subclass of NSEnumerator whose instances return a single object before finishing. */
@interface GRXNSScalarEnumerator : NSEnumerator
// Param value: the single object this instance will produce. After the first invocation of
// nextObject, the value is released.
/**
* Param value: the single object this instance will produce. After the first invocation of
* nextObject, the value is released.
*/
- (instancetype)initWithValue:(id)value;
@end

@ -33,7 +33,7 @@
#import "RxLibrary/GRXForwardingWriter.h"
// A "proxy" writer that transforms all the values of its input writer by using a mapping function.
/** A "proxy" writer that transforms all the values of its input writer by using a mapping function. */
@interface GRXMappingWriter : GRXForwardingWriter
- (instancetype)initWithWriter:(GRXWriter *)writer map:(id (^)(id value))map
NS_DESIGNATED_INITIALIZER;

Loading…
Cancel
Save