PeerCache

/* Copyright 2022-2026 Thales Alenia Space
 * Licensed to CS GROUP (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * CS licenses this file to You 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.
 */
package org.orekit.frames;

import org.hipparchus.CalculusFieldElement;
import org.hipparchus.Field;
import org.orekit.time.AbsoluteDate;
import org.orekit.time.FieldAbsoluteDate;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.locks.StampedLock;
import java.util.function.Function;
import java.util.function.Supplier;

/** Cache for frame transforms.
 * <p>
 * This class is thread-safe.
 * </p>
 * @author Luc Maisonobe
 * @since 13.1
 */
class PeerCache {

    /** Origin frame. */
    private final Frame origin;

    /** Cache for transforms with peer frame. */
    private volatile CachedTransformProvider cache;

    /** Lock for peer frame cache. */
    private final StampedLock lock;

    /** Cache for transforms with peer frame. */
    private volatile Map<Field<? extends CalculusFieldElement<?>>, FieldCachedTransformProvider<?>> fieldCaches;

    /** create an instance not associated with any peer.
     * @param origin origin frame
     */
    PeerCache(final Frame origin) {
        this.origin      = origin;
        this.cache       = null;
        this.fieldCaches = null;
        this.lock        = new StampedLock();
    }

    /** Associate a cache with a peer frame, caching transforms.
     * <p>
     * The cache is a LRU cache (Least Recently Used), so entries remain in
     * the cache if they are used frequently, and only older entries
     * that have not been accessed for a while will be expunged.
     * </p>
     * <p>
     * If a peer was already associated with this frame, it will be overridden.
     * </p>
     * <p>
     * Peering is unidirectional, i.e. if frameA is peered with frameB,
     * then frameB may be peered with another frameC or no frame at all.
     * This allows several frames to be peered with a pivot one (typically
     * Earth frame and many topocentric frames all peered with one inertial frame).
     * </p>
     * @param peer peer frame (if null, cache is cleared)
     * @param cacheSize number of transforms kept in the date-based cache
     */
    public void setPeerCaching(final Frame peer, final int cacheSize) {
        final long lockId = lock.writeLock();
        try {
            if (peer == null) {
                // clear peering
                cache       = null;
                fieldCaches = null;
            } else {
                // caching for regular dates
                cache       = createCache(peer, cacheSize);
                // caching for field dates
                fieldCaches = new ConcurrentHashMap<>();
            }
        } finally {
            lock.unlockWrite(lockId);
        }
    }

    /** Get the peer associated to this frame.
     * @return peer associated with this frame, null if not peered at all
     */
    Frame getPeer() {
        if (cache == null) {
            return null;
        } else {
            return optimisticRead(this::getPeerDestination);
        }
    }

    private Frame getPeerDestination() {
        return cache == null ? null : cache.getDestination();
    }

    /** Get the cached transform provider associated with this destination.
     * @param destination destination frame to which we want to transform vectors
     * @return cached transform provider, or null if destination is not the instance peer
     */
    CachedTransformProvider getCachedTransformProvider(final Frame destination) {
        if (cache == null)  {
            return null;
        } else {
            return optimisticRead(() -> getProvider(destination));
        }
    }

    private CachedTransformProvider getProvider(final Frame destination) {
        final Frame peerDestination = getPeerDestination();
        if (peerDestination == null || peerDestination != destination) {
            return null;
        } else {
            return cache;
        }
    }

    /** Get the cached transform provider associated with this destination.
     * @param <T> the type of the field elements
     * @param destination destination frame to which we want to transform vectors
     * @param field field elements belong to
     * @return cached transform provider, or null if destination is not the instance peer
     */
    <T extends CalculusFieldElement<T>> FieldCachedTransformProvider<T> getCachedTransformProvider(final Frame destination,
                                                                                                   final Field<T> field) {
        if (cache == null) {
            return null;
        } else {
            return optimisticRead(() -> getFieldProvider(destination, field));
        }
    }

    private <T> T optimisticRead(final Supplier<T> readFunction) {
        final long optimisticLockId = lock.tryOptimisticRead();
        final T optimisticResult = readFunction.get();
        if (lock.validate(optimisticLockId)) {
            return optimisticResult;
        } else {
            final long heavyLockId = lock.readLock();
            try {
                return readFunction.get();
            } finally {
                lock.unlockRead(heavyLockId);
            }
        }
    }

    @SuppressWarnings("unchecked")
    private <T extends CalculusFieldElement<T>> FieldCachedTransformProvider<T> getFieldProvider(final Frame destination, final Field<T> field) {
        final CachedTransformProvider provider = getProvider(destination);
        if (provider == null) {
            return null;
        } else {
            return (FieldCachedTransformProvider<T>) fieldCaches.computeIfAbsent(field, f -> createCache(destination,
                                                                                  provider.getCacheSize(),
                                                                                  field));
        }
    }

    /** Create cache.
     * @param peer peer frame
     * @param cacheSize number of transforms kept in the date-based cache
     * @return built cache
     * @since 13.0.3
     */
    private CachedTransformProvider createCache(final Frame peer, final int cacheSize) {
        final Function<AbsoluteDate, Transform> fullGenerator =
                date -> origin.getTransformTo(peer,
                                              Transform.IDENTITY,
                                              frame -> frame.getTransformProvider().getTransform(date),
                                              (t1, t2) -> new Transform(date, t1, t2),
                                              Transform::getInverse);
        final Function<AbsoluteDate, KinematicTransform> kinematicGenerator =
                date -> origin.getTransformTo(peer,
                                              KinematicTransform.getIdentity(),
                                              frame -> frame.getTransformProvider().getTransform(date),
                                              (t1, t2) -> KinematicTransform.compose(date, t1, t2),
                                              KinematicTransform::getInverse);
        final Function<AbsoluteDate, StaticTransform> staticGenerator =
                date -> origin.getTransformTo(peer,
                                              StaticTransform.getIdentity(),
                                              frame -> frame.getTransformProvider().getTransform(date),
                                              (t1, t2) -> StaticTransform.compose(date, t1, t2),
                                              StaticTransform::getInverse);
        return new CachedTransformProvider(origin, peer,
                                           fullGenerator, kinematicGenerator, staticGenerator,
                                           cacheSize);
    }

    /** Create field cache.
     * @param <T> type of the field elements
     * @param peer peer frame
     * @param cacheSize number of transforms kept in the date-based cache
     * @param field field elements belong to
     * @return built cache
     * @since 13.0.3
     */
    private <T extends CalculusFieldElement<T>> FieldCachedTransformProvider<T>
        createCache(final Frame peer, final int cacheSize, final Field<T> field) {
        final Function<FieldAbsoluteDate<T>, FieldTransform<T>> fullGenerator =
                d -> origin.getTransformTo(peer,
                                           FieldTransform.getIdentity(field),
                                           frame -> frame.getTransformProvider().getTransform(d),
                                           (FieldTransform<T> t1, FieldTransform<T> t2) -> new FieldTransform<>(d, t1, t2),
                                           FieldTransform::getInverse);
        final Function<FieldAbsoluteDate<T>, FieldKinematicTransform<T>> kinematicGenerator =
                d -> origin.getTransformTo(peer,
                                           FieldKinematicTransform.getIdentity(field),
                                           frame -> frame.getTransformProvider().getTransform(d),
                                           (t1, t2) -> FieldKinematicTransform.compose(d, t1, t2),
                                           FieldKinematicTransform::getInverse);
        final Function<FieldAbsoluteDate<T>, FieldStaticTransform<T>> staticGenerator =
                d -> origin.getTransformTo(peer,
                                           FieldStaticTransform.getIdentity(field),
                                           frame -> frame.getTransformProvider().getTransform(d),
                                           (t1, t2) -> FieldStaticTransform.compose(d, t1, t2),
                                           FieldStaticTransform::getInverse);
        return new FieldCachedTransformProvider<>(origin, peer,
                                                  fullGenerator, kinematicGenerator, staticGenerator,
                                                  cacheSize);
    }

}