revised Swift comments, API cleanup

Packages/gRPC/Sources/Call.swift

@@ -76,7 +76,7 @@ public class Call {
   /// - Parameter operations: array of operations to be performed
   /// - Parameter tag: integer tag that will be attached to these operations
   /// - Returns: the result of initiating the call
-  public func performOperations(operations: OperationGroup,
+  func performOperations(operations: OperationGroup,
                                 tag: Int64,
                                 completionQueue: CompletionQueue)
     -> grpc_call_error {
@@ -90,8 +90,6 @@ public class Call {
 
   /// Performs a nonstreaming gRPC API call
   ///
-  /// - Parameter host: the gRPC host name for the call
-  /// - Parameter method: the gRPC method name for the call
   /// - Parameter message: a ByteBuffer containing the message to send
   /// - Parameter metadata: metadata to send with the call
   /// - Returns: a CallResponse object containing results of the call
@@ -132,13 +130,22 @@ public class Call {
     print ("call error = \(call_error)")
   }
 
-  public func perform(call: Call, operations: OperationGroup) -> grpc_call_error {
+  // perform a group of operations (used internally)
+  private func perform(call: Call, operations: OperationGroup) -> grpc_call_error {
     self.completionQueue.operationGroups[operations.tag] = operations
     return call.performOperations(operations:operations,
                                   tag:operations.tag,
                                   completionQueue: self.completionQueue)
   }
 
+  // start a streaming connection
+  public func start(metadata: Metadata) {
+    self.sendInitialMetadata(metadata: metadata)
+    self.receiveInitialMetadata()
+    self.receiveStatus()
+  }
+
+  // send a message over a streaming connection
   public func sendMessage(data: NSData) {
     let messageBuffer = ByteBuffer(data:data)
     let operation_sendMessage = Operation_SendMessage(message:messageBuffer)
@@ -152,6 +159,7 @@ public class Call {
     }
   }
 
+  // receive a message over a streaming connection
   public func receiveMessage(callback:((NSData!) -> Void)) -> Void {
     let operation_receiveMessage = Operation_ReceiveMessage()
     let operations = OperationGroup(call:self, operations:[operation_receiveMessage])
@@ -167,13 +175,7 @@ public class Call {
     }
   }
 
-  // start a streaming connection
-  public func start(metadata: Metadata) {
-    self.sendInitialMetadata(metadata: metadata)
-    self.receiveInitialMetadata()
-    self.receiveStatus()
-  }
-
+  // send initial metadata over a streaming connection
   private func sendInitialMetadata(metadata: Metadata) {
     let operation_sendInitialMetadata = Operation_SendInitialMetadata(metadata:metadata);
     let operations = OperationGroup(call:self, operations:[operation_sendInitialMetadata])
@@ -191,6 +193,7 @@ public class Call {
     }
   }
 
+  // receive initial metadata from a streaming connection
   private func receiveInitialMetadata() {
     let operation_receiveInitialMetadata = Operation_ReceiveInitialMetadata()
     let operations = OperationGroup(call:self, operations:[operation_receiveInitialMetadata])
@@ -207,6 +210,7 @@ public class Call {
     }
   }
 
+  // receive status from a streaming connection
   private func receiveStatus() {
     let operation_receiveStatus = Operation_ReceiveStatusOnClient()
     let operations = OperationGroup(call:self,
@@ -221,6 +225,7 @@ public class Call {
     }
   }
 
+  // close a streaming connection
   public func close(completion:(() -> Void)) {
     let operation_sendCloseFromClient = Operation_SendCloseFromClient()
     let operations = OperationGroup(call:self, operations:[operation_sendCloseFromClient])

Packages/gRPC/Sources/Client.swift

@@ -62,7 +62,7 @@ public class Client {
   /// - Parameter host: the gRPC host name for the call
   /// - Parameter method: the gRPC method name for the call
   /// - Parameter timeout: a timeout value in seconds
-  /// - Returns: a Call object that can be used to make the request
+  /// - Returns: a Call object that can be used to perform the request
   public func createCall(host:String, method:String, timeout:Double) -> Call {
     let call = cgrpc_client_create_call(c, method, host, timeout)!
     return Call(call:call, owned:true, completionQueue:self.completionQueue)

Packages/gRPC/Sources/CompletionQueue.swift

@@ -60,6 +60,7 @@ public class CompletionQueue {
     return cgrpc_completion_queue_get_next_event(cq, timeout);
   }
 
+  /// Run a completion queue
   public func run(completion:@escaping () -> Void) {
     DispatchQueue.global().async {
       var running = true

Packages/gRPC/Sources/Handler.swift

@@ -151,12 +151,12 @@ public class Handler {
     _ = call.performOperations(operations:operations, tag:operations.tag, completionQueue: self.completionQueue)
   }
 
-
+  /// shutdown the handler's completion queue
   public func shutdown() {
     cgrpc_completion_queue_shutdown(completionQueue.cq)
   }
 
-
+  /// Send initial metadata in response to a connection
   public func sendMetadata(initialMetadata: Metadata,
                            completion:(() -> Void)) {
     let call = self.call()
@@ -215,6 +215,7 @@ public class Handler {
     _ = call.performOperations(operations:operations, tag:operations.tag, completionQueue: self.completionQueue)
   }
 
+  /// Recognize when the client has closed a request
   public func receiveClose(completion: @escaping () -> Void) -> Void {
     let call = self.call()
     let operation_receiveClose = Operation_ReceiveCloseOnServer()
@@ -228,6 +229,7 @@ public class Handler {
     print("perform receiveClose \(call_error)")
   }
 
+  /// Send final status to the client
   public func sendStatus(trailingMetadata: Metadata,
                          completion:(() -> Void)) -> Void {
     let call = self.call()
@@ -242,6 +244,4 @@ public class Handler {
     self.completionQueue.operationGroups[operations.tag] = operations
     _ = call.performOperations(operations:operations, tag:operations.tag, completionQueue: self.completionQueue)
   }
-
-
 }

Packages/gRPC/Sources/OperationGroup.swift

@@ -34,20 +34,34 @@
   import CgRPC
 #endif
 
+/// Singleton class that provides a mutex for synchronizing tag generation
+private class OperationGroupTagLock {
+  var mutex : Mutex
+  init() {
+    mutex = Mutex()
+  }
+  static let sharedInstance = OperationGroupTagLock()
+}
+
 /// A collection of gRPC operations
 public class OperationGroup {
 
+  /// Used to generate unique tags for OperationGroups
   static var nextTag : Int64 = 1
 
+  /// Automatically-assigned tag that is used with the completion queue.
+  public var tag : Int64
+
+  /// The call associated with the operation group. Retained while the operations are running.
   var call : Call
 
-  public var tag : Int64
+  /// An array of operation objects that are passed into the initializer
+  var operationsArray : [Operation]?
 
   /// Pointer to underlying C representation
   var operations : UnsafeMutableRawPointer!
 
-  var operationsArray : [Operation]?
-
+  /// Completion handler that is called when the group completes
   var completion : ((grpc_event) -> Void)
 
   /// Initializes a Operations representation
@@ -65,12 +79,11 @@ public class OperationGroup {
     }
     self.completion = completion
 
+    let mutex = OperationGroupTagLock.sharedInstance.mutex
+    mutex.lock()
     self.tag = OperationGroup.nextTag
     OperationGroup.nextTag += 1
-  }
-
-  deinit {
-    
+    mutex.unlock()
   }
 }
 

Packages/gRPC/Sources/Server.swift

@@ -60,13 +60,9 @@ public class Server {
     cgrpc_server_destroy(s)
   }
 
-  /// Starts the server
-  public func start() {
-    cgrpc_server_start(s);
-  }
-
+  /// Run the server
   public func run(handler: @escaping (Handler) -> Void) {
-    self.start()
+    cgrpc_server_start(s);
     DispatchQueue.global().async {
       while(true) {
         let (callError, completionType, requestHandler) =
@@ -87,7 +83,7 @@ public class Server {
   /// Gets the next request sent to the server
   ///
   /// - Returns: a tuple containing the results of waiting and a possible Handler for the request
-  public func getNextRequest(timeout: Double) -> (grpc_call_error, grpc_completion_type, Handler?) {
+  private func getNextRequest(timeout: Double) -> (grpc_call_error, grpc_completion_type, Handler?) {
     let handler = Handler(h:cgrpc_handler_create_with_server(s))
     let call_error = handler.requestCall(tag:101)
     if (call_error != GRPC_CALL_OK) {

Packages/gRPC/Sources/Writable.swift

@@ -1,42 +0,0 @@
-/*
- *
- * Copyright 2016, 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.
- *
- */
-#if SWIFT_PACKAGE
-  import CgRPC
-#endif
-import Foundation
-
-// An object to which a sequence of values can be sent
-protocol Writable {
-  func writeValue(value: Any)
-  func writeFinished(with error: NSError)
-}

Packages/gRPC/Sources/Writer.swift

@@ -1,72 +0,0 @@
-/*
- *
- * Copyright 2016, 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.
- *
- */
-#if SWIFT_PACKAGE
-  import CgRPC
-#endif
-import Foundation
-
-enum WriterState {
-  /**
-   * 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.
-   */
-  case NotStarted
-
-  /** The writer might push values to the writeable at any moment. */
-  case Started
-
-  /**
-   * 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.
-   */
-  case Paused
-
-  /**
-   * 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.
-   */
-  case Finished
-}
-
-// An object that can produce a sequence of values by calling a Writable
-protocol Writer {
-  var state: Int {get set}
-  func start(with writable:Writable)
-  func finish(with error:NSError)
-}

gRPC.xcodeproj/project.pbxproj

@@ -7,8 +7,6 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		D310E3C21D5D8B89002D48D0 /* Writer.swift in Sources */ = {isa = PBXBuildFile; fileRef = D310E3C11D5D8B89002D48D0 /* Writer.swift */; };
-		D310E3C71D5D8CD8002D48D0 /* Writable.swift in Sources */ = {isa = PBXBuildFile; fileRef = D310E3C61D5D8CD8002D48D0 /* Writable.swift */; };
 		D32F10121D5CEE880071B7C1 /* CallResponse.swift in Sources */ = {isa = PBXBuildFile; fileRef = D32F10111D5CEE880071B7C1 /* CallResponse.swift */; };
 		D34B4BB81D7B2C9B00B8B5E2 /* OperationGroup.swift in Sources */ = {isa = PBXBuildFile; fileRef = D34B4BB71D7B2C9B00B8B5E2 /* OperationGroup.swift */; };
 		D34B4BBA1D7B2CB200B8B5E2 /* operations.c in Sources */ = {isa = PBXBuildFile; fileRef = D34B4BB91D7B2CB200B8B5E2 /* operations.c */; };
@@ -40,8 +38,6 @@
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
-		D310E3C11D5D8B89002D48D0 /* Writer.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = Writer.swift; path = Packages/gRPC/Sources/Writer.swift; sourceTree = "<group>"; };
-		D310E3C61D5D8CD8002D48D0 /* Writable.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = Writable.swift; path = Packages/gRPC/Sources/Writable.swift; sourceTree = "<group>"; };
 		D32F10111D5CEE880071B7C1 /* CallResponse.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = CallResponse.swift; path = Packages/gRPC/Sources/CallResponse.swift; sourceTree = "<group>"; };
 		D34B4BB71D7B2C9B00B8B5E2 /* OperationGroup.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; name = OperationGroup.swift; path = Packages/gRPC/Sources/OperationGroup.swift; sourceTree = "<group>"; };
 		D34B4BB91D7B2CB200B8B5E2 /* operations.c */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.c; name = operations.c; path = Packages/CgRPC/Sources/operations.c; sourceTree = "<group>"; };
@@ -122,8 +118,6 @@
 				D3AC86C31D5BEBE00042B341 /* Operation.swift */,
 				D34B4BB71D7B2C9B00B8B5E2 /* OperationGroup.swift */,
 				D3AC86C41D5BEBE00042B341 /* Server.swift */,
-				D310E3C61D5D8CD8002D48D0 /* Writable.swift */,
-				D310E3C11D5D8B89002D48D0 /* Writer.swift */,
 			);
 			name = gRPC/Sources;
 			sourceTree = "<group>";
@@ -262,12 +256,10 @@
 				D3AC86C81D5BEBE00042B341 /* CompletionQueue.swift in Sources */,
 				D3AC86C61D5BEBE00042B341 /* Call.swift in Sources */,
 				D3AC86CB1D5BEBE00042B341 /* Metadata.swift in Sources */,
-				D310E3C71D5D8CD8002D48D0 /* Writable.swift in Sources */,
 				D3AC86C91D5BEBE00042B341 /* gRPC.swift in Sources */,
 				D34B4BB81D7B2C9B00B8B5E2 /* OperationGroup.swift in Sources */,
 				D3AC86CA1D5BEBE00042B341 /* Handler.swift in Sources */,
 				D3AC86CD1D5BEBE00042B341 /* Operation.swift in Sources */,
-				D310E3C21D5D8B89002D48D0 /* Writer.swift in Sources */,
 				D37DD0281D7D09CB009AEB74 /* event.c in Sources */,
 				D32F10121D5CEE880071B7C1 /* CallResponse.swift in Sources */,
 				D3AC86CE1D5BEBE00042B341 /* Server.swift in Sources */,