add example for OnCodes (#85)
diff --git a/v2/example_test.go b/v2/example_test.go
new file mode 100644
index 0000000..dd3653e
--- /dev/null
+++ b/v2/example_test.go
@@ -0,0 +1,94 @@
+// Copyright 2019, 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.
+
+package gax_test
+
+import (
+ "context"
+ "time"
+
+ "github.com/googleapis/gax-go/v2"
+ "google.golang.org/grpc/codes"
+)
+
+const someRPCTimeout = 5 * time.Minute
+
+// Some result that the client might return.
+type fakeResponse struct{}
+
+// Some client that can perform RPCs.
+type fakeClient struct{}
+
+// PerformSomeRPC is a fake RPC that a client might perform.
+func (c *fakeClient) PerformSomeRPC(ctx context.Context) (*fakeResponse, error) {
+ // An actual client would return something meaningful here.
+ return nil, nil
+}
+
+func ExampleOnCodes() {
+ ctx := context.Background()
+ c := &fakeClient{}
+
+ // UNKNOWN and UNAVAILABLE are typically safe to retry for idempotent RPCs.
+ retryer := gax.OnCodes([]codes.Code{codes.Unknown, codes.Unavailable}, gax.Backoff{
+ Initial: time.Second,
+ Max: 32 * time.Second,
+ Multiplier: 2,
+ })
+
+ performSomeRPCWithRetry := func(ctx context.Context) (*fakeResponse, error) {
+ for {
+ resp, err := c.PerformSomeRPC(ctx)
+ if err != nil {
+ if delay, shouldRetry := retryer.Retry(err); shouldRetry {
+ if err := gax.Sleep(ctx, delay); err != nil {
+ return nil, err
+ }
+ continue
+ }
+ return nil, err
+ }
+ return resp, err
+ }
+ }
+
+ // It's recommended to set deadlines on RPCs and around retrying. This is
+ // also usually preferred over setting some fixed number of retries: one
+ // advantage this has is that backoff settings can be changed independently
+ // of the deadline, whereas with a fixed number of retries the deadline
+ // would be a constantly-shifting goalpost.
+ ctxWithTimeout, cancel := context.WithDeadline(ctx, time.Now().Add(someRPCTimeout))
+ defer cancel()
+
+ resp, err := performSomeRPCWithRetry(ctxWithTimeout)
+ if err != nil {
+ // TODO: handle err
+ }
+ _ = resp // TODO: use resp if err is nil
+}
