srkukarni commented on a change in pull request #1838: Pulsar Go client docs URL: https://github.com/apache/incubator-pulsar/pull/1838#discussion_r196909559
########## File path: site/docs/latest/clients/go.md ########## @@ -0,0 +1,589 @@ +--- +title: The Pulsar Go client +tags: [client, go, golang] +--- + +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> + +The Pulsar Go client can be used to create Pulsar [producers](#producers), [consumers](#consumers), and [readers](#readers) in Go (aka Golang). + +{% include admonition.html type="info" title="API docs available as well" + content="For standard API docs, consult the [Godoc](https://godoc.org/github.com/apache/incubator-pulsar/pulsar-client-go/pulsar)." %} + +## Installation + +You can install the `pulsar` library locally using `go get`: + +```bash +$ go get -u github.com/apache/incubator-pulsar/pulsar-client-go/pulsar +``` + +Once installed locally, you can import it into your project: + +```go +import "github.com/apache/incubator-pulsar/pulsar-client-go/pulsar" +``` + +## Connection URLs {#urls} + +{% include explanations/client-url.md %} + +## Creating a client + +In order to interact with Pulsar, you'll first need a `Client` object. You can create a client object using the `NewClient` function, passing in a `ClientOptions` object (more on configuration [below](#client-configuration)). Here's an example: + + +```go +import ( + "log" + "runtime" + + "github.com/apache/incubator-pulsar/pulsar-client-go/pulsar" +) + +func main() { + cores := runtime.NumCPU() + + clientOpts := pulsar.ClientOptions{ + URL: "pulsar://localhost:6650", + OperationTimeoutSeconds: 5, + MessageListenerThreads: cores, + } + + client, err := pulsar.NewClient(clientOpts) + + if err != nil { + log.Fatalf("Could not instantiate Pulsar client: %v", err) + } +} +``` + +### Client configuration + +You can configure your Pulsar client using a `ClientOptions` object. Here's an example: + +```go +import ( + "log" + "runtime" + + "github.com/apache/incubator-pulsar/pulsar-client-go/pulsar" +) + +func main() { + cores := runtime.NumCPU() + + clientOpts := pulsar.ClientOptions{ + URL: "pulsar://localhost:6650", + OperationTimeoutSeconds: 5, + MessageListenerThreads: runtime.NumCPU(), + } + + client, err := pulsar.NewClient(clientOpts) + + if err != nil { + log.Fatalf("Could not instantiate Pulsar client: %v", err) + } +} +``` + +The following configurable parameters are available for Pulsar clients: + +Parameter | Description | Default +:---------|:------------|:------- +`URL` | The connection URL for the Pulsar cluster. See [above](#urls) for more info | +`IOThreads` | The number of threads to use for handling connections to Pulsar {% popover brokers %} | 1 +`OperationTimeoutSeconds` | The timeout for some Go client operations (creating producers, subscribing to and unsubscribing from {% popover topics %}). Retries will occur until this threshold is reached, at which point the operation will fail. | 30 +`MessageListenerThreads` | The number of threads used by message listeners ([consumers](#consumers) and [readers](#readers)) | 1 +`ConcurrentLookupRequests` | The number of concurrent lookup requests that can be sent on each broker connection. Setting a maximum helps to keep from overloading brokers. You should set values over the default of 5000 only if the client needs to produce and/or subscribe to thousands of Pulsar topics. | 5000 +`Logger` | A custom logger implementation for the client (as a function that takes a log level, filepath, line number, and message). All info, warn, and error messages will be routed to this function. +`EnableTLS` | Whether [TLS](#tls) encryption is enabled for the client | `false` +`TLSTrustCertsFilePath` | The filepath for the trusted TLS certificate | +`TLSAllowInsecureConnection` | Whether the client accepts untrusted TLS certificates from the broker | `false` +`StatsIntervalInSeconds` | The interval (in seconds) at which client stats are published | 60 + +## Producers + +Pulsar {% popover producers %} publish messages to Pulsar {% popover topics %}. You can [configure](#producer-configuration) Go producers using a `ProducerOptions` object. Here's an example: + +```go +producerOpts := pulsar.ProducerOptions{ + Topic: "my-topic", +} + +producer, err := client.CreateProducer(producerOpts) + +if err != nil { + log.Fatalf("Could not instantiate Pulsar producer: %v", err) +} + +defer producer.Close() + +msg := pulsar.ProducerMessage{ + Payload: []byte("Hello, Pulsar"), +} + +if err := producer.Send(msg); err != nil { + log.Fatalf("Producer could not send message: %v", err) +} +``` + +{% include admonition.html type="warning" title="Blocking operation" + content="When you create a new Pulsar producer, the operation will block until either a producer is successfully created or an error is thrown." %} + +### Producer operations + +Pulsar Go producers have the following methods available: + +Method | Description | Return type +:------|:------------|:----------- +`Topic()` | Fetches the producer's {% popover topic %} | `string` +`Name()` | Fetchs the producer's name | `string` +`Send(context.Context, ProducerMessage) error` | Publishes a [message](#messages) to the producer's topic. This call will block until the message is successfully acknowledged by the Pulsar broker, or an error will be thrown if the timeout set using the `SendTimeout` in the producer's [configuration](#producer-configuration) is exceeded. | `error` +`SendAsync(context.Context, ProducerMessage, func(ProducerMessage, error))` | Publishes a [message](#messages) to the producer's topic asynchronously. The third argument is a callback function that specifies what happens either when the message is acknowledged or an error is thrown. | +`Close()` | Closes the producer and releases all resources allocated to it. If `Close()` is called then no more messages will be accepted from the publisher. This method will block until all pending publish requests have been persisted by Pulsar. If an error is thrown, no pending writes will be retried. | `error` + +Here's a more involved example usage of a producer: + +```go +import ( + "context" + "fmt" + + "github.com/apache/incubator-pulsar/pulsar-client-go/pulsar" +) + +func main() { + // Instantiate a Pulsar client + client, err := pulsar.NewClient(pulsar.ClientOptions{ + URL: "pulsar://localhost:6650", + }) + + if err != nil { log.Fatal(err) } + + // Use the client to instantiate a producer + producer, err := client.CreateProducer(pulsar.ProducerOptions{ + Topic: "my-topic", + }) + + if err != nil { log.Fatal(err) } + + ctx := context.Background() + + // Send 10 messages synchronously and 10 messages asynchronously + for i := 0; i < 10; i++ { + // Create a message + msg := pulsar.ProducerMessage{ + Payload: []byte(fmt.Sprintf("message-%d", i)), + } + + // Attempt to send the message + if err := producer.Send(ctx, msg); err != nil { + log.Fatal(err) + } + + // Create a different message to send asynchronously + asyncMsg := pulsar.ProducerMessage{ + Payload: []byte(fmt.Sprintf("async-message-%d", i)), + } + + // Attempt to send the message asynchronously and handle the response + producer.SendAsync(ctx, asyncMsg, func(msg pulsar.ProducerMessage, err error) { + if err != nil { log.Fatal(err) } + + fmt.Printf("Message %s succesfully published", msg.ID()) + }) + } +} +``` + +### Producer configuration Review comment: Shouldnt this be worded as producer options? ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
