and
<a href="/pkg/sync/#WaitGroup">wait groups</a>.
The documentation for each of these specifies the guarantees it
makes concerning synchronization.
</p>

<p>
Other packages that provide synchronization abstractions
should document the guarantees they make too.
</p>


<h2 id="badsync">Incorrect synchronization</h2>

<p>
Programs with races are incorrect and

            // So that is why we cancel only in the case of CAS success.
            taskFuture.cancel(false);
          }
        };
    // Adding the listener to both futures guarantees that newFuture will always be set. Adding to
    // taskFuture guarantees completion if the callable is invoked, and adding to outputFuture
    // propagates cancellation if the callable has not yet been invoked.

   * service changes state. The listener will not have previous state changes replayed, so it is
   * suggested that listeners are added before the service starts.
   *
   * <p>{@code addListener} guarantees execution ordering across calls to a given listener but not
   * across calls to multiple listeners. Specifically, a given listener will have its callbacks

existing object replication are not marked as `PENDING` prior to replication.

   * compares as equal to the key.
   */
  enum KeyPresentBehavior {
    /**
     * Return the index of any list element that compares as equal to the key. No guarantees are
     * made as to which index is returned, if more than one element compares as equal to the key.
     */
    ANY_PRESENT {
      @Override
      <E extends @Nullable Object> int resultIndex(

   * @param array the source array
   * @param minLength the minimum length the returned array must guarantee
   * @param padding an extra amount to "grow" the array by if growth is necessary
   * @throws IllegalArgumentException if {@code minLength} or {@code padding} is negative
   * @return an array containing the values of {@code array}, with guaranteed minimum length {@code
   *     minLength}
   */

   * @param array the source array
   * @param minLength the minimum length the returned array must guarantee
   * @param padding an extra amount to "grow" the array by if growth is necessary
   * @throws IllegalArgumentException if {@code minLength} or {@code padding} is negative
   * @return an array containing the values of {@code array}, with guaranteed minimum length {@code
   *     minLength}
   */

        }
        catch ( TransportException e ) {
            cleanupThread(timeout);
            throw e;
        }
        finally {
            /*
             * This guarantees that we leave in a valid state
             */
            st = this.state;
            if ( st != 0 && st != 3 && st != 4 && st != 5 && st != 6 ) {
                log.error("Invalid state: " + st);

   * and response body streams; otherwise resources may be leaked.
   *
   * This method is safe to be called concurrently, but provides limited guarantees. If a transport
   * layer connection has been established (such as a HTTP/2 stream) that is terminated. Otherwise
   * if a socket connection is being established, that is terminated.
   */
  override fun cancel() {

   * Iterator} is a "weakly consistent" iterator that will never throw {@link
   * ConcurrentModificationException}, and guarantees to traverse elements as they existed upon
   * construction of the iterator, and may (but is not guaranteed to) reflect any modifications
   * subsequent to construction.
   *
   * @return an iterator over the elements in this queue in proper sequence
   */