diff --git a/examples/objective-c/auth_sample/AuthTestService.podspec b/examples/objective-c/auth_sample/AuthTestService.podspec index 9f2a2cc361b..9521d4971a8 100644 --- a/examples/objective-c/auth_sample/AuthTestService.podspec +++ b/examples/objective-c/auth_sample/AuthTestService.podspec @@ -3,13 +3,13 @@ Pod::Spec.new do |s| s.version = "0.0.1" s.license = "New BSD" - s.ios.deployment_target = "6.0" - s.osx.deployment_target = "10.8" + s.ios.deployment_target = "7.1" + s.osx.deployment_target = "10.9" # Base directory where the .proto files are. src = "../../protos" - # Directory where the generated files will be place. + # Directory where the generated files will be placed. dir = "Pods/" + s.name # Run protoc with the Objective-C and gRPC plugins to generate protocol messages and gRPC clients. @@ -22,14 +22,14 @@ Pod::Spec.new do |s| ms.source_files = "#{dir}/*.pbobjc.{h,m}", "#{dir}/**/*.pbobjc.{h,m}" ms.header_mappings_dir = dir ms.requires_arc = false - ms.dependency "Protobuf", "~> 3.0.0-alpha-3" + ms.dependency "Protobuf", "~> 3.0.0-alpha-4" end s.subspec "Services" do |ss| ss.source_files = "#{dir}/*.pbrpc.{h,m}", "#{dir}/**/*.pbrpc.{h,m}" ss.header_mappings_dir = dir ss.requires_arc = true - ss.dependency "gRPC", "~> 0.6" + ss.dependency "gRPC", "~> 0.11" ss.dependency "#{s.name}/Messages" end end diff --git a/examples/objective-c/auth_sample/MakeRPCViewController.m b/examples/objective-c/auth_sample/MakeRPCViewController.m index 366bc9deea9..4fd23dc1448 100644 --- a/examples/objective-c/auth_sample/MakeRPCViewController.m +++ b/examples/objective-c/auth_sample/MakeRPCViewController.m @@ -35,7 +35,6 @@ #import #import -#include #import NSString * const kTestScope = @"https://www.googleapis.com/auth/xapi.zoo"; @@ -49,10 +48,10 @@ static NSString * const kTestHostAddress = @"grpc-test.sandbox.google.com"; @implementation NSError (AuthSample) - (NSString *)UIDescription { - if (self.code == GRPC_STATUS_UNAUTHENTICATED) { + if (self.code == GRPCErrorCodeUnauthenticated) { // Authentication error. OAuth2 specifies we'll receive a challenge header. - // |userInfo[kGRPCStatusMetadataKey]| is the dictionary of response metadata. - NSString *challengeHeader = self.userInfo[kGRPCStatusMetadataKey][@"www-authenticate"] ?: @""; + // |userInfo[kGRPCHeadersKey]| is the dictionary of response headers. + NSString *challengeHeader = self.userInfo[kGRPCHeadersKey][@"www-authenticate"] ?: @""; return [@"Invalid credentials. Server challenge:\n" stringByAppendingString:challengeHeader]; } else { // Any other error. @@ -89,7 +88,7 @@ static NSString * const kTestHostAddress = @"grpc-test.sandbox.google.com"; // Set the access token to be used. NSString *accessToken = GIDSignIn.sharedInstance.currentUser.authentication.accessToken; - call.requestMetadata[@"Authorization"] = [@"Bearer " stringByAppendingString:accessToken]; + call.requestHeaders[@"Authorization"] = [@"Bearer " stringByAppendingString:accessToken]; // Start the RPC. [call start]; diff --git a/examples/objective-c/auth_sample/Podfile b/examples/objective-c/auth_sample/Podfile index dd4fd558c0e..ea70511dc6c 100644 --- a/examples/objective-c/auth_sample/Podfile +++ b/examples/objective-c/auth_sample/Podfile @@ -1,6 +1,9 @@ source 'https://github.com/CocoaPods/Specs.git' platform :ios, '8.0' +pod 'Protobuf', :path => "../../../third_party/protobuf" +pod 'gRPC', :path => "../../.." + target 'AuthSample' do # Depend on the generated AuthTestService library. pod 'AuthTestService', :path => '.' diff --git a/examples/objective-c/route_guide/Podfile b/examples/objective-c/route_guide/Podfile index a97f4146858..efa46bba4fa 100644 --- a/examples/objective-c/route_guide/Podfile +++ b/examples/objective-c/route_guide/Podfile @@ -2,6 +2,8 @@ source 'https://github.com/CocoaPods/Specs.git' platform :ios, '8.0' target 'RouteGuideClient' do + pod 'Protobuf', :path => "../../../third_party/protobuf" + pod 'gRPC', :path => "../../.." # Depend on the generated RouteGuide library. pod 'RouteGuide', :path => '.' end diff --git a/examples/objective-c/route_guide/RouteGuide.podspec b/examples/objective-c/route_guide/RouteGuide.podspec index 7b99a6c6a77..e00f827e3a4 100644 --- a/examples/objective-c/route_guide/RouteGuide.podspec +++ b/examples/objective-c/route_guide/RouteGuide.podspec @@ -3,13 +3,13 @@ Pod::Spec.new do |s| s.version = "0.0.1" s.license = "New BSD" - s.ios.deployment_target = "6.0" - s.osx.deployment_target = "10.8" + s.ios.deployment_target = "7.1" + s.osx.deployment_target = "10.9" # Base directory where the .proto files are. src = "../../protos" - # Directory where the generated files will be place. + # Directory where the generated files will be placed. dir = "Pods/" + s.name # Run protoc with the Objective-C and gRPC plugins to generate protocol messages and gRPC clients. @@ -22,14 +22,14 @@ Pod::Spec.new do |s| ms.source_files = "#{dir}/*.pbobjc.{h,m}", "#{dir}/**/*.pbobjc.{h,m}" ms.header_mappings_dir = dir ms.requires_arc = false - ms.dependency "Protobuf", "~> 3.0.0-alpha-3" + ms.dependency "Protobuf", "~> 3.0.0-alpha-4" end s.subspec "Services" do |ss| ss.source_files = "#{dir}/*.pbrpc.{h,m}", "#{dir}/**/*.pbrpc.{h,m}" ss.header_mappings_dir = dir ss.requires_arc = true - ss.dependency "gRPC", "~> 0.6" + ss.dependency "gRPC", "~> 0.11" ss.dependency "#{s.name}/Messages" end end diff --git a/include/grpc++/support/sync_stream.h b/include/grpc++/support/sync_stream.h index 514363338d8..daf4e367aeb 100644 --- a/include/grpc++/support/sync_stream.h +++ b/include/grpc++/support/sync_stream.h @@ -131,7 +131,7 @@ class ClientReader GRPC_FINAL : public ClientReaderInterface { cq_.Pluck(&ops); } - void WaitForInitialMetadata() { + void WaitForInitialMetadata() GRPC_OVERRIDE { GPR_ASSERT(!context_->initial_metadata_received_); CallOpSet ops; @@ -257,7 +257,7 @@ class ClientReaderWriter GRPC_FINAL : public ClientReaderWriterInterface { cq_.Pluck(&ops); } - void WaitForInitialMetadata() { + void WaitForInitialMetadata() GRPC_OVERRIDE { GPR_ASSERT(!context_->initial_metadata_received_); CallOpSet ops; diff --git a/src/objective-c/GRPCClient/GRPCCall+OAuth2.h b/src/objective-c/GRPCClient/GRPCCall+OAuth2.h index 2e379a71572..6b443877e9b 100644 --- a/src/objective-c/GRPCClient/GRPCCall+OAuth2.h +++ b/src/objective-c/GRPCClient/GRPCCall+OAuth2.h @@ -33,17 +33,19 @@ #import "GRPCCall.h" -// Helpers for setting and reading headers compatible with OAuth2. +/** Helpers for setting and reading headers compatible with OAuth2. */ @interface GRPCCall (OAuth2) -// Setting this property is equivalent to setting "Bearer " as the value of the -// request header with key "authorization" (the authorization header). Setting it to nil removes the -// authorization header from the request. -// The value obtained by getting the property is the OAuth2 bearer token if the authorization header -// of the request has the form "Bearer ", or nil otherwise. +/** + * Setting this property is equivalent to setting "Bearer " as the value of the + * request header with key "authorization" (the authorization header). Setting it to nil removes the + * authorization header from the request. + * The value obtained by getting the property is the OAuth2 bearer token if the authorization header + * of the request has the form "Bearer ", or nil otherwise. + */ @property(atomic, copy) NSString *oauth2AccessToken; -// Returns the value (if any) of the "www-authenticate" response header (the challenge header). +/** Returns the value (if any) of the "www-authenticate" response header (the challenge header). */ @property(atomic, readonly) NSString *oauth2ChallengeHeader; @end diff --git a/src/objective-c/GRPCClient/GRPCCall+Tests.h b/src/objective-c/GRPCClient/GRPCCall+Tests.h index cca16146063..ccc5723ec70 100644 --- a/src/objective-c/GRPCClient/GRPCCall+Tests.h +++ b/src/objective-c/GRPCClient/GRPCCall+Tests.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 diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h index 35f7e16af70..5918f8857a9 100644 --- a/src/objective-c/GRPCClient/GRPCCall.h +++ b/src/objective-c/GRPCClient/GRPCCall.h @@ -31,117 +31,145 @@ * */ -// The gRPC protocol is an RPC protocol on top of HTTP2. -// -// While the most common type of RPC receives only one request message and returns only one response -// message, the protocol also supports RPCs that return multiple individual messages in a streaming -// fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and -// responses. -// -// Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of -// the "non-streaming type" sending only one message in the corresponding direction (the protocol -// doesn't make any distinction). -// -// Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed -// transparently on the same TCP connection. +/** + * The gRPC protocol is an RPC protocol on top of HTTP2. + * + * While the most common type of RPC receives only one request message and returns only one response + * message, the protocol also supports RPCs that return multiple individual messages in a streaming + * fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and + * responses. + * + * Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of + * the "non-streaming type" sending only one message in the corresponding direction (the protocol + * doesn't make any distinction). + * + * Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed + * transparently on the same TCP connection. + */ #import #import #pragma mark gRPC errors -// Domain of NSError objects produced by gRPC. +/** Domain of NSError objects produced by gRPC. */ extern NSString *const kGRPCErrorDomain; -// gRPC error codes. -// Note that a few of these are never produced by the gRPC libraries, but are of general utility for -// server applications to produce. +/** + * gRPC error codes. + * Note that a few of these are never produced by the gRPC libraries, but are of general utility for + * 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, - // Unknown error. Errors raised by APIs that do not return enough error information may be - // converted to this error. + /** + * Unknown error. Errors raised by APIs that do not return enough error information may be + * converted to this error. + */ GRPCErrorCodeUnknown = 2, - // The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. - // INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the - // server (e.g., a malformed file name). + /** + * The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. + * INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the + * server (e.g., a malformed file name). + */ GRPCErrorCodeInvalidArgument = 3, - // Deadline expired before operation could complete. For operations that change the state of the - // server, this error may be returned even if the operation has completed successfully. For - // example, a successful response from the server could have been delayed long enough for the - // deadline to expire. + /** + * Deadline expired before operation could complete. For operations that change the state of the + * server, this error may be returned even if the operation has completed successfully. For + * example, a successful response from the server could have been delayed long enough for the + * deadline to expire. + */ GRPCErrorCodeDeadlineExceeded = 4, - // Some requested entity (e.g., file or directory) was not found. + /** Some requested entity (e.g., file or directory) was not found. */ GRPCErrorCodeNotFound = 5, - // Some entity that we attempted to create (e.g., file or directory) already exists. + /** Some entity that we attempted to create (e.g., file or directory) already exists. */ GRPCErrorCodeAlreadyExists = 6, - // The caller does not have permission to execute the specified operation. PERMISSION_DENIED isn't - // used for rejections caused by exhausting some resource (RESOURCE_EXHAUSTED is used instead for - // those errors). PERMISSION_DENIED doesn't indicate a failure to identify the caller - // (UNAUTHENTICATED is used instead for those errors). + /** + * The caller does not have permission to execute the specified operation. PERMISSION_DENIED isn't + * used for rejections caused by exhausting some resource (RESOURCE_EXHAUSTED is used instead for + * those errors). PERMISSION_DENIED doesn't indicate a failure to identify the caller + * (UNAUTHENTICATED is used instead for those errors). + */ GRPCErrorCodePermissionDenied = 7, - // The request does not have valid authentication credentials for the operation (e.g. the caller's - // identity can't be verified). + /** + * The request does not have valid authentication credentials for the operation (e.g. the caller's + * identity can't be verified). + */ GRPCErrorCodeUnauthenticated = 16, - // Some resource has been exhausted, perhaps a per-user quota. + /** Some resource has been exhausted, perhaps a per-user quota. */ GRPCErrorCodeResourceExhausted = 8, - // The RPC was rejected because the server is not in a state required for the procedure's - // execution. For example, a directory to be deleted may be non-empty, etc. - // The client should not retry until the server state has been explicitly fixed (e.g. by - // performing another RPC). The details depend on the service being called, and should be found in - // the NSError's userInfo. + /** + * The RPC was rejected because the server is not in a state required for the procedure's + * execution. For example, a directory to be deleted may be non-empty, etc. + * The client should not retry until the server state has been explicitly fixed (e.g. by + * performing another RPC). The details depend on the service being called, and should be found in + * the NSError's userInfo. + */ GRPCErrorCodeFailedPrecondition = 9, - // The RPC was aborted, typically due to a concurrency issue like sequencer check failures, - // transaction aborts, etc. The client should retry at a higher-level (e.g., restarting a read- - // modify-write sequence). + /** + * The RPC was aborted, typically due to a concurrency issue like sequencer check failures, + * transaction aborts, etc. The client should retry at a higher-level (e.g., restarting a read- + * modify-write sequence). + */ GRPCErrorCodeAborted = 10, - // The RPC was attempted past the valid range. E.g., enumerating past the end of a list. - // Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state - // changes. For example, an RPC to get elements of a list will generate INVALID_ARGUMENT if asked - // to return the element at a negative index, but it will generate OUT_OF_RANGE if asked to return - // the element at an index past the current size of the list. + /** + * The RPC was attempted past the valid range. E.g., enumerating past the end of a list. + * Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state + * changes. For example, an RPC to get elements of a list will generate INVALID_ARGUMENT if asked + * to return the element at a negative index, but it will generate OUT_OF_RANGE if asked to return + * the element at an index past the current size of the list. + */ GRPCErrorCodeOutOfRange = 11, - // The procedure is not implemented or not supported/enabled in this server. + /** The procedure is not implemented or not supported/enabled in this server. */ GRPCErrorCodeUnimplemented = 12, - // Internal error. Means some invariant expected by the server application or the gRPC library has - // been broken. + /** + * Internal error. Means some invariant expected by the server application or the gRPC library has + * been broken. + */ GRPCErrorCodeInternal = 13, - // The server is currently unavailable. This is most likely a transient condition and may be - // corrected by retrying with a backoff. + /** + * The server is currently unavailable. This is most likely a transient condition and may be + * corrected by retrying with a backoff. + */ GRPCErrorCodeUnavailable = 14, - // Unrecoverable data loss or corruption. + /** Unrecoverable data loss or corruption. */ GRPCErrorCodeDataLoss = 15, }; -// Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by -// the server. +/** + * Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by + * the server. + */ extern id const kGRPCHeadersKey; extern id const kGRPCTrailersKey; #pragma mark GRPCCall -// The container of the request headers of an RPC conforms to this protocol, which is a subset of -// NSMutableDictionary's interface. It will become a NSMutableDictionary later on. -// The keys of this container are the header names, which per the HTTP standard are case- -// insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and -// can only consist of ASCII characters. -// A header value is a NSString object (with only ASCII characters), unless the header name has the -// suffix "-bin", in which case the value has to be a NSData object. +/** + * The container of the request headers of an RPC conforms to this protocol, which is a subset of + * NSMutableDictionary's interface. It will become a NSMutableDictionary later on. + * The keys of this container are the header names, which per the HTTP standard are case- + * insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and + * can only consist of ASCII characters. + * A header value is a NSString object (with only ASCII characters), unless the header name has the + * suffix "-bin", in which case the value has to be a NSData object. + */ @protocol GRPCRequestHeaders @property(nonatomic, readonly) NSUInteger count; @@ -154,53 +182,63 @@ extern id const kGRPCTrailersKey; @end -// Represents a single gRPC remote call. +/** Represents a single gRPC remote call. */ @interface GRPCCall : GRXWriter -// These HTTP headers will be passed to the server as part of this call. Each HTTP header is a -// name-value pair with string names and either string or binary values. -// -// The passed dictionary has to use NSString keys, corresponding to the header names. The value -// associated to each can be a NSString object or a NSData object. E.g.: -// -// call.requestHeaders = @{@"authorization": @"Bearer ..."}; -// -// call.requestHeaders[@"my-header-bin"] = someData; -// -// After the call is started, trying to modify this property is an error. -// -// The property is initialized to an empty NSMutableDictionary. +/** + * These HTTP headers will be passed to the server as part of this call. Each HTTP header is a + * name-value pair with string names and either string or binary values. + * + * The passed dictionary has to use NSString keys, corresponding to the header names. The value + * associated to each can be a NSString object or a NSData object. E.g.: + * + * call.requestHeaders = @{@"authorization": @"Bearer ..."}; + * + * call.requestHeaders[@"my-header-bin"] = someData; + * + * After the call is started, trying to modify this property is an error. + * + * The property is initialized to an empty NSMutableDictionary. + */ @property(atomic, readonly) id requestHeaders; -// This dictionary is populated with the HTTP headers received from the server. This happens before -// any response message is received from the server. It has the same structure as the request -// headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a -// NSData value; the others have a NSString value. -// -// The value of this property is nil until all response headers are received, and will change before -// any of -writeValue: or -writesFinishedWithError: are sent to the writeable. +/** + * This dictionary is populated with the HTTP headers received from the server. This happens before + * any response message is received from the server. It has the same structure as the request + * headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a + * NSData value; the others have a NSString value. + * + * The value of this property is nil until all response headers are received, and will change before + * any of -writeValue: or -writesFinishedWithError: are sent to the writeable. + */ @property(atomic, readonly) NSDictionary *responseHeaders; -// Same as responseHeaders, but populated with the HTTP trailers received from the server before the -// call finishes. -// -// The value of this property is nil until all response trailers are received, and will change -// before -writesFinishedWithError: is sent to the writeable. +/** + * Same as responseHeaders, but populated with the HTTP trailers received from the server before the + * call finishes. + * + * The value of this property is nil until all response trailers are received, and will change + * before -writesFinishedWithError: is sent to the writeable. + */ @property(atomic, readonly) NSDictionary *responseTrailers; -// The request writer has to write NSData objects into the provided Writeable. The server will -// receive each of those separately and in order as distinct messages. -// A gRPC call might not complete until the request writer finishes. On the other hand, the request -// finishing doesn't necessarily make the call to finish, as the server might continue sending -// messages to the response side of the call indefinitely (depending on the semantics of the -// specific remote method called). -// To finish a call right away, invoke cancel. +/** + * The request writer has to write NSData objects into the provided Writeable. The server will + * receive each of those separately and in order as distinct messages. + * A gRPC call might not complete until the request writer finishes. On the other hand, the request + * finishing doesn't necessarily make the call to finish, as the server might continue sending + * messages to the response side of the call indefinitely (depending on the semantics of the + * specific remote method called). + * To finish a call right away, invoke cancel. + */ - (instancetype)initWithHost:(NSString *)host path:(NSString *)path requestsWriter:(GRXWriter *)requestsWriter NS_DESIGNATED_INITIALIZER; -// Finishes the request side of this call, notifies the server that the RPC should be cancelled, and -// finishes the response side of the call with an error of code CANCELED. +/** + * Finishes the request side of this call, notifies the server that the RPC should be cancelled, and + * finishes the response side of the call with an error of code CANCELED. + */ - (void)cancel; // TODO(jcanizales): Let specify a deadline. As a category of GRXWriter? diff --git a/src/objective-c/GRPCClient/private/GRPCChannel.h b/src/objective-c/GRPCClient/private/GRPCChannel.h index 2a7b701576a..e2d19d506ad 100644 --- a/src/objective-c/GRPCClient/private/GRPCChannel.h +++ b/src/objective-c/GRPCClient/private/GRPCChannel.h @@ -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 diff --git a/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h b/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h index ab8d714d220..fe3b8f39d12 100644 --- a/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h +++ b/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h @@ -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; diff --git a/src/objective-c/GRPCClient/private/GRPCHost.h b/src/objective-c/GRPCClient/private/GRPCHost.h index f0bbd530234..6b4f98746d0 100644 --- a/src/objective-c/GRPCClient/private/GRPCHost.h +++ b/src/objective-c/GRPCClient/private/GRPCHost.h @@ -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; diff --git a/src/objective-c/GRPCClient/private/GRPCSecureChannel.h b/src/objective-c/GRPCClient/private/GRPCSecureChannel.h index 74257eb0584..4e0881e5a2a 100644 --- a/src/objective-c/GRPCClient/private/GRPCSecureChannel.h +++ b/src/objective-c/GRPCClient/private/GRPCSecureChannel.h @@ -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; diff --git a/src/objective-c/GRPCClient/private/GRPCWrappedCall.h b/src/objective-c/GRPCClient/private/GRPCWrappedCall.h index 4ca2766147e..7747aa53ef0 100644 --- a/src/objective-c/GRPCClient/private/GRPCWrappedCall.h +++ b/src/objective-c/GRPCClient/private/GRPCWrappedCall.h @@ -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 diff --git a/src/objective-c/GRPCClient/private/NSError+GRPC.h b/src/objective-c/GRPCClient/private/NSError+GRPC.h index f4729dc8a13..e0c1efc1f91 100644 --- a/src/objective-c/GRPCClient/private/NSError+GRPC.h +++ b/src/objective-c/GRPCClient/private/NSError+GRPC.h @@ -35,7 +35,9 @@ #include @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 diff --git a/src/objective-c/ProtoRPC/ProtoMethod.h b/src/objective-c/ProtoRPC/ProtoMethod.h index 8f554a04832..a0ed2cf98a5 100644 --- a/src/objective-c/ProtoRPC/ProtoMethod.h +++ b/src/objective-c/ProtoRPC/ProtoMethod.h @@ -33,8 +33,10 @@ #import -// 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; diff --git a/src/objective-c/RxLibrary/GRXBufferedPipe.h b/src/objective-c/RxLibrary/GRXBufferedPipe.h index ca94ce275f7..03b0359278a 100644 --- a/src/objective-c/RxLibrary/GRXBufferedPipe.h +++ b/src/objective-c/RxLibrary/GRXBufferedPipe.h @@ -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 -// Convenience constructor. +/** Convenience constructor. */ + (instancetype)pipe; @end diff --git a/src/objective-c/RxLibrary/GRXConcurrentWriteable.h b/src/objective-c/RxLibrary/GRXConcurrentWriteable.h index 1080001905e..b2775f98b56 100644 --- a/src/objective-c/RxLibrary/GRXConcurrentWriteable.h +++ b/src/objective-c/RxLibrary/GRXConcurrentWriteable.h @@ -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)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 diff --git a/src/objective-c/RxLibrary/GRXForwardingWriter.h b/src/objective-c/RxLibrary/GRXForwardingWriter.h index f310832284a..8d45b8ed8d3 100644 --- a/src/objective-c/RxLibrary/GRXForwardingWriter.h +++ b/src/objective-c/RxLibrary/GRXForwardingWriter.h @@ -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 diff --git a/src/objective-c/RxLibrary/GRXImmediateWriter.h b/src/objective-c/RxLibrary/GRXImmediateWriter.h index 3fcc2594342..e22b056ff56 100644 --- a/src/objective-c/RxLibrary/GRXImmediateWriter.h +++ b/src/objective-c/RxLibrary/GRXImmediateWriter.h @@ -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)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 diff --git a/src/objective-c/RxLibrary/GRXWriteable.h b/src/objective-c/RxLibrary/GRXWriteable.h index 45613d6dd09..7fe805c6638 100644 --- a/src/objective-c/RxLibrary/GRXWriteable.h +++ b/src/objective-c/RxLibrary/GRXWriteable.h @@ -33,16 +33,20 @@ #import -// 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 -// 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 + (instancetype)writeableWithSingleHandler:(GRXSingleHandler)handler; diff --git a/src/objective-c/RxLibrary/GRXWriter+Immediate.h b/src/objective-c/RxLibrary/GRXWriter+Immediate.h index b75c0a5a64c..be880151f4f 100644 --- a/src/objective-c/RxLibrary/GRXWriter+Immediate.h +++ b/src/objective-c/RxLibrary/GRXWriter+Immediate.h @@ -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)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 diff --git a/src/objective-c/RxLibrary/GRXWriter+Transformations.h b/src/objective-c/RxLibrary/GRXWriter+Transformations.h index 60c4da37d69..17d61e75410 100644 --- a/src/objective-c/RxLibrary/GRXWriter+Transformations.h +++ b/src/objective-c/RxLibrary/GRXWriter+Transformations.h @@ -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 diff --git a/src/objective-c/RxLibrary/GRXWriter.h b/src/objective-c/RxLibrary/GRXWriter.h index b1c994aa382..ff81268446a 100644 --- a/src/objective-c/RxLibrary/GRXWriter.h +++ b/src/objective-c/RxLibrary/GRXWriter.h @@ -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)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 diff --git a/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h b/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h index 400e834c6ae..0622f7067c0 100644 --- a/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h +++ b/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h @@ -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)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 diff --git a/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h index 34cfc4d8a77..fb50c37863a 100644 --- a/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h +++ b/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h @@ -33,10 +33,14 @@ #import -// 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 diff --git a/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h index 15650292055..62c27dbc7f3 100644 --- a/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h +++ b/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h @@ -33,11 +33,15 @@ #import -// 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)container; @end diff --git a/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h index 12aa51e2139..24a21a1b22c 100644 --- a/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h +++ b/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h @@ -33,9 +33,11 @@ #import -// 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 diff --git a/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h b/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h index 43b87068647..01a15e2a430 100644 --- a/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h +++ b/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h @@ -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; diff --git a/src/objective-c/change-comments.py b/src/objective-c/change-comments.py new file mode 100755 index 00000000000..9aa0e0c9f5a --- /dev/null +++ b/src/objective-c/change-comments.py @@ -0,0 +1,128 @@ +#!/usr/bin/env python2.7 +# Copyright 2015, Google Inc. +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are +# met: +# +# * Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above +# copyright notice, this list of conditions and the following disclaimer +# in the documentation and/or other materials provided with the +# distribution. +# * Neither the name of Google Inc. nor the names of its +# contributors may be used to endorse or promote products derived from +# this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +"""Change comments style of source files from // to /** */""" + +import re +import sys + + +if len(sys.argv) < 2: + print("Please provide at least one source file name as argument.") + sys.exit() + +for file_name in sys.argv[1:]: + + print("Modifying format of {file} comments in place...".format( + file=file_name, + )) + + + # Input + + with open(file_name, "r") as input_file: + lines = input_file.readlines() + + def peek(): + return lines[0] + + def read_line(): + return lines.pop(0) + + def more_input_available(): + return lines + + + # Output + + output_lines = [] + + def write(line): + output_lines.append(line) + + def flush_output(): + with open(file_name, "w") as output_file: + for line in output_lines: + output_file.write(line) + + + # Pattern matching + + comment_regex = r'^(\s*)//\s(.*)$' + + def is_comment(line): + return re.search(comment_regex, line) + + def isnt_comment(line): + return not is_comment(line) + + def next_line(predicate): + return more_input_available() and predicate(peek()) + + + # Transformation + + def indentation_of(line): + match = re.search(comment_regex, line) + return match.group(1) + + def content(line): + match = re.search(comment_regex, line) + return match.group(2) + + def format_as_block(comment_block): + if len(comment_block) == 0: + return [] + + indent = indentation_of(comment_block[0]) + + if len(comment_block) == 1: + return [indent + "/** " + content(comment_block[0]) + " */\n"] + + block = ["/**"] + [" * " + content(line) for line in comment_block] + [" */"] + return [indent + line.rstrip() + "\n" for line in block] + + + # Main algorithm + + while more_input_available(): + while next_line(isnt_comment): + write(read_line()) + + comment_block = [] + # Get all lines in the same comment block. We could restrict the indentation + # to be the same as the first line of the block, but it's probably ok. + while (next_line(is_comment)): + comment_block.append(read_line()) + + for line in format_as_block(comment_block): + write(line) + + flush_output() diff --git a/src/objective-c/format-all-comments.sh b/src/objective-c/format-all-comments.sh new file mode 100644 index 00000000000..e6b6b5a0b49 --- /dev/null +++ b/src/objective-c/format-all-comments.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# Copyright 2015, Google Inc. +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are +# met: +# +# * Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above +# copyright notice, this list of conditions and the following disclaimer +# in the documentation and/or other materials provided with the +# distribution. +# * Neither the name of Google Inc. nor the names of its +# contributors may be used to endorse or promote products derived from +# this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +find . -type f -name "*.h" ! -path "*/Pods/*" ! -path "./generated_libraries/*" ! -path "./examples/*" ! -path "./tests/*" | xargs ./change-comments.py