com.google.appengine.api.quota.QuotaService Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of appengine-api-1.0-sdk
API for Google App Engine standard environment with some of the dependencies shaded (repackaged)
There is a newer version: 2.0.27
/*
 * Copyright 2021 Google LLC
 *
 * 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
 *
 *     https://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 com.google.appengine.api.quota;

/**
 * The {@code QuotaService} provides measurement of API and CPU usage
 * during requests.
 *
 */
public interface QuotaService {

  /**
   * Represents all types of data that a QuotaService might be able to provide.
   */
  enum DataType {
    API_TIME_IN_MEGACYCLES,
    CPU_TIME_IN_MEGACYCLES;
  }

  /**
   * Tests if the QuotaService can provide a certain kind of data at this
   * point in time. Depending on the underlying app server implementation and
   * what state it is in, a QuotaService might not always have access to all
   * categories of data. For example, the dev-appserver might not be able to
   * measure the megacycles of api calls. Trying to access that data would lead
   * to an IllegalStateException, which would then need to be handled. To make
   * it easier to prevent this, it is possible to ask the service if a
   * particular kind of data is supported.
   *
   * @param type the type of data in question.
   * @return true if the QuotaService can provide such data at this time.
   * @exception NullPointerException if a null argument is passed into
   *   the method.
   */
  boolean supports(DataType type);

  /**
   * @deprecated This value is no longer meaningful.
   * @return the overall amount spent in API cycles, as returned by the system.
   *   Returns 0 if the feature is not supported.
   */
  @Deprecated
  long getApiTimeInMegaCycles();

  /**
   * Measures the duration that the current request has spent so far processing
   * the request within the App Engine sandbox. Note that time spent in API
   * calls will not be added to this value.
   * 
   * The unit the duration is measured is Megacycles. If all instructions
   * were to be executed sequentially on a standard 1.2 GHz 64-bit x86 CPU,
   * 1200 megacycles would equate to one second physical time elapsed.
   *
   * @return the overall amount spent in CPU cycles, as returned by the system.
   *   Returns 0 if the feature is not supported.
   */
  long getCpuTimeInMegaCycles();

  /**
   * Expresses a value in megaCycles as its approximate equivalent of CPU
   * seconds on a theoretical 1.2 GHz CPU.
   *
   * @param megaCycles the value, in megacycles, to convert.
   * @return a double representing the CPU-seconds the input megacycle value
   *    converts to.
   */
  double convertMegacyclesToCpuSeconds(long megaCycles);

  /**
   * Expresses a value in megaCycles as its approximate equivalent of CPU
   * seconds on a theoretical 1.2 GHz CPU.
   *
   * @param cpuSeconds the value, in cpu seconds, to convert.
   * @return a long representing the megacycles the input CPU-seconds value
   *    converts to.
   */
  long convertCpuSecondsToMegacycles(double cpuSeconds);

}