Add java.time.Duration overloads to CallOptions, AbstractStub, Deadline, and other APIs

[kluever]

Is your feature request related to a problem?

long, TimeUnit APIs encourage plumbing a pair of variables through various layers, or require plumbing a single ambiguous numeric primitive (e.g., long deadlineInSeconds). The modern alternative is to use a java.time.Duration.

Describe the solution you'd like

Every API that requests a long, TimeUnit should have a java.time.Duration overload as well

Describe alternatives you've considered

n/a

Additional context

n/a

[kluever]

Also leaving a breadcrumb that Eric mentioned to me: those methods will probably need the org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement annotation on them.

[ejona86]

We still support non-javatime on Android, so these will need to be surface-level conveniences only. They should immediately convert to the current long-timeunit tuple methods.

[kluever]

SGTM --- this is very similar to what we do in Guava APIs that historically accept a long, TimeUnit tuple. E.g., https://github.com/google/guava/blob/master/guava/src/com/google/common/util/concurrent/Futures.java#L222-L259

You'll likely want to decompose to nanoseconds, but be aware of the potential for overflow (which happens at +/- 292 years). We've been using a helper function to decompose a Duration safely:
https://github.com/google/guava/blob/master/guava/src/com/google/common/util/concurrent/Internal.java#L27-L42

[ejona86]

TimeUnit.NANOSECONDS.convert(duration) looks better than Duration.toNano() for us, as it saturates and we aren't trying to avoid TimeUnit.

APIs that would be quick:
CallOptions
Deadline
AbstractStub

Then there's a longer tail:
ManagedChannelBuilder (and transport-specific friends)
ServerBuilder
... certainly there are others

Dunno about these and blocking methods in general. The only occurrence in java.util.concerrent is TimeUnit. I don't see a single blocking method have Duration in Java, so I think we'll leave the awaitTermination and blocking as old-style:
(don't change these)
ManagedChannel
Server

[kluever]

Thanks! My understanding is that the JDK folks have been a bit apprehensive about adding Duration-based overloads to java.util.concurrent APIs, since most of those APIs are very low-level concurrency building blocks (and allocation could matter in some cases). However, for user-facing APIs such as gRPC, Duration is almost certainly going to be better for your users.

[shubhamraj-samsung]

/assign

[shubhamraj-samsung]

@kluever @ejona86 Hi I am new to open source and would like to contribute to this issue. Please assign this issue to me

[ejona86]

Huh. I was able to assign you. I thought folks had to be in the grpc org for that to work.

[shubhamraj-samsung]

Hi @ejona86
I have implemented java.time.Duration overload function for CallOptions as follows. Please check if this is what you are expecting

   /**
   * Returns a new {@code CallOptions} with a deadline that is after the given {@code duration} from
   * now.
   */
    // This is my overloaded function with the **toNanosSaturated method** mentioned by @kluever 
  public CallOptions withDeadlineAfter(Duration duration) {
    return withDeadlineAfter(Deadline.after(toNanosSaturated(delay), TimeUnit.NANOSECONDS));
  }


  /**
   * Returns a new {@code CallOptions} with a deadline that is after the given {@code duration} from
   * now.
   */
  public CallOptions withDeadlineAfter(long duration, TimeUnit unit) {
    return withDeadline(Deadline.after(duration, unit));
  }

[shubhamraj-samsung]

My question is where should I create the java file for method toNanosSaturated(delay)
I thank you in advance for your patience:)

[kluever]

In Guava, we just made a package-private Internal.java class in each package where we wanted to use it: https://github.com/google/guava/blob/master/guava/src/com/google/common/util/concurrent/Internal.java#L27-L42

I'm not sure if gRPC can use Java 11+ APIs, but if so, you could do what @ejona86 suggested above: TimeUnit.convert(Duration)