grpc
/
grpc-java
mirror of https://github.com/grpc/grpc-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

core: refine LoadBalancer javadoc (#6950) 

Update renamed components and references to deprecated APIs.
This commit is contained in:
Kun Zhang 2020-04-20 15:51:36 -07:00 committed by GitHub
parent d63f2b439c
commit 54cac75d47
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
api/src/main/java/io/grpc/LoadBalancer.java
View File

@ -75,18 +75,19 @@ import javax.annotation.concurrent.ThreadSafe;
* synchronization primitives, blocking I/O, blocking RPCs, etc.</li> * synchronization primitives, blocking I/O, blocking RPCs, etc.</li>
* *
* <li><strong>Avoid calling into other components with lock held</strong>. The Synchronization * <li><strong>Avoid calling into other components with lock held</strong>. The Synchronization
* Context may be under a lock, e.g., the transport lock of OkHttp. If your LoadBalancer has a * Context may be under a lock, e.g., the transport lock of OkHttp. If your LoadBalancer holds a
* lock, holds the lock in a callback method (e.g., {@link #handleSubchannelState * lock in a callback method (e.g., {@link #handleResolvedAddresses handleResolvedAddresses()})
* handleSubchannelState()}) while calling into another class that may involve locks, be cautious * while calling into another method that also involves locks, be cautious of deadlock. Generally
* of deadlock. Generally you wouldn't need any locking in the LoadBalancer.</li> * you wouldn't need any locking in the LoadBalancer if you follow the canonical implementation
* pattern below.</li>
* *
* </ol> * </ol>
* *
* <h3>The canonical implementation pattern</h3> * <h3>The canonical implementation pattern</h3>
* *
* <p>A {@link LoadBalancer} keeps states like the latest addresses from NameResolver, the * <p>A {@link LoadBalancer} keeps states like the latest addresses from NameResolver, the
* Subchannel(s) and their latest connectivity states. These states are mutated within the Channel * Subchannel(s) and their latest connectivity states. These states are mutated within the
* Executor. * Synchronization Context,
* *
* <p>A typical {@link SubchannelPicker SubchannelPicker} holds a snapshot of these states. It may * <p>A typical {@link SubchannelPicker SubchannelPicker} holds a snapshot of these states. It may
* have its own states, e.g., a picker from a round-robin load-balancer may keep a pointer to the * have its own states, e.g., a picker from a round-robin load-balancer may keep a pointer to the
@ -95,9 +96,10 @@ import javax.annotation.concurrent.ThreadSafe;
* picker only needs to synchronize its own states, which is typically trivial to implement. * picker only needs to synchronize its own states, which is typically trivial to implement.
* *
* <p>When the LoadBalancer states changes, e.g., Subchannels has become or stopped being READY, and * <p>When the LoadBalancer states changes, e.g., Subchannels has become or stopped being READY, and
* we want subsequent RPCs to use the latest list of READY Subchannels, LoadBalancer would create * we want subsequent RPCs to use the latest list of READY Subchannels, LoadBalancer would create a
* a new picker, which holds a snapshot of the latest Subchannel list. Refer to the javadoc of * new picker, which holds a snapshot of the latest Subchannel list. Refer to the javadoc of {@link
* {@link #handleSubchannelState handleSubchannelState()} how to do this properly. * io.grpc.LoadBalancer.SubchannelStateListener#onSubchannelState onSubchannelState()} how to do
* this properly.
* *
* <p>No synchronization should be necessary between LoadBalancer and its pickers if you follow * <p>No synchronization should be necessary between LoadBalancer and its pickers if you follow
* the pattern above. It may be possible to implement in a different way, but that would usually * the pattern above. It may be possible to implement in a different way, but that would usually