Add async examples update

opentracing-api/src/main/java/io/opentracing/Scope.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2016-2017 The OpenTracing Authors
+ *
+ * Licensed 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.
+ */
+package io.opentracing;
+
+import java.io.Closeable;
+
+/**
+ * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint.
+ *
+ * <p>
+ * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a
+ * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an
+ * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given
+ * {@link Span} <em>is</em> scheduled and on the path.
+ */
+public interface Scope extends Closeable {
+    /**
+     * Mark the end of the active period for the current thread and {@link Scope},
+     * updating the {@link ScopeManager#active()} in the process.
+     *
+     * <p>
+     * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined
+     * behavior.
+     */
+    @Override
+    void close();
+
+    /**
+     * @return the {@link Span} that's been scoped by this {@link Scope}
+     */
+    Span span();
+}