001/*
002 * Java Genetic Algorithm Library (jenetics-7.0.0).
003 * Copyright (c) 2007-2022 Franz Wilhelmstötter
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 * Author:
018 *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
019 */
020package io.jenetics.prog.regression;
021
022import static java.util.Objects.requireNonNull;
023
024import java.util.Arrays;
025import java.util.Collection;
026import java.util.List;
027import java.util.Objects;
028
029import io.jenetics.ext.util.Tree;
030
031import io.jenetics.prog.op.Op;
032
033/**
034 * This class holds the actual sample values which are used for the symbolic
035 * regression example. This class is <em>thread-safe</em> and can be used in a
036 * <em>producer-consumer</em> setup. You can add single sample values
037 * ({@link #add(Sample)}) or a list ({@link #addAll(Collection)}) of new values.
038 * These values will be made available for evaluation after an explicit call of
039 * the {@link #publish()} method.
040 *
041 * @implNote
042 * This class is thread-safe.
043 *
044 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
045 * @version 6.0
046 * @since 6.0
047 */
048public final class SampleBuffer<T> implements Sampling<T> {
049
050        private final RingBuffer _buffer;
051
052        private volatile SampleList<T> _snapshot = null;
053
054        public SampleBuffer(final int capacity) {
055                _buffer = new RingBuffer(capacity);
056        }
057
058        /**
059         * Adding a new sample point to the buffer. <em>You need to explicitly
060         * call {@link #publish()} to make it available for the {@link #eval(Tree)}
061         * method.</em>
062         *
063         * @param sample the sample point to add
064         * @throws NullPointerException if the given {@code sample} point is
065         *         {@code null}
066         */
067        public void add(final Sample<T> sample) {
068                _buffer.add(requireNonNull(sample));
069        }
070
071        /**
072         * The the given sample points to the buffer.  <em>You need to explicitly
073         * call {@link #publish()} to make it available for the {@link #eval(Tree)}
074         * method.</em>
075         *
076         * @param samples the samples to add to the buffer
077         * @throws NullPointerException if the given {@code samples} is {@code null}
078         */
079        public void addAll(final Collection<? extends Sample<T>> samples) {
080                samples.forEach(Objects::requireNonNull);
081                _buffer.addAll(samples);
082        }
083
084        /**
085         * Making the current sample points available for the {@link #eval(Tree)}
086         * function.
087         *
088         * @return the number of <em>published</em> sample points
089         */
090        @SuppressWarnings({"unchecked", "rawtypes"})
091        public int publish() {
092                final Object[] values = _buffer.snapshot();
093
094                SampleList<T> snapshot = null;
095                if (values != null && values.length > 0) {
096                        final List samples = Arrays.asList(values);
097                        snapshot = new SampleList(samples);
098                }
099
100                try {
101                        return snapshot != null ? snapshot.size() : 0;
102                } finally {
103                        _snapshot = snapshot;
104                }
105        }
106
107        /**
108         * Return the currently <em>published</em> sample points.
109         *
110         * @see #publish()
111         *
112         * @return the currently <em>published</em> sample points
113         */
114        List<Sample<T>> samples() {
115                final SampleList<T> snapshot = _snapshot;
116                return snapshot != null ? snapshot : List.of();
117        }
118
119        @Override
120        public Result<T> eval(final Tree<? extends Op<T>, ?> program) {
121                requireNonNull(program);
122
123                final SampleList<T> snapshot = _snapshot;
124                return snapshot != null && !snapshot.isEmpty()
125                        ? snapshot.eval(program)
126                        : null;
127        }
128
129}