# Copyright 2018 The dm_control 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.
# ============================================================================

"""Decorators for Entity methods returning elements and observables."""

import abc
import threading


class cached_property(property):  # pylint: disable=invalid-name
  """A property that is evaluated only once per object instance."""

  def __init__(self, func, doc=None):
    super().__init__(fget=func, doc=doc)
    self.lock = threading.RLock()

  def __get__(self, obj, cls):
    if obj is None:
      return self
    name = self.fget.__name__
    obj_dict = obj.__dict__
    try:
      # Try returning a precomputed value without locking first.
      # Profiling shows that the lock takes up a non-trivial amount of time.
      return obj_dict[name]
    except KeyError:
      # The value hasn't been computed, now we have to lock.
      with self.lock:
        try:
          # Check again whether another thread has already computed the value.
          return obj_dict[name]
        except KeyError:
          # Otherwise call the function, cache the result, and return it
          return obj_dict.setdefault(name, self.fget(obj))


# A decorator for base.Observables methods returning an observable. This
# decorator should be used by abstract base classes to indicate sub-classes need
# to implement a corresponding @observavble annotated method.
abstract_observable = abc.abstractproperty  # pylint: disable=invalid-name


class observable(cached_property):  # pylint: disable=invalid-name
  """A decorator for base.Observables methods returning an observable.

  The body of the decorated function is evaluated at Entity construction time
  and the observable is cached.
  """
  pass