/* * Copyright 2014 Higher Frequency Trading * * http://www.higherfrequencytrading.com * * 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. */ package net.openhft.chronicle.map; import net.openhft.chronicle.hash.ChronicleHash; import net.openhft.chronicle.hash.serialization.BytesReader; import net.openhft.lang.io.Bytes; import net.openhft.lang.io.serialization.BytesMarshaller; import net.openhft.lang.model.Byteable; import org.jetbrains.annotations.NotNull; import java.io.Closeable; import java.util.Map; import java.util.concurrent.ConcurrentMap; /** * Extension of {@link ConcurrentMap} interface, stores the data off-heap. * *

For information on

see {@link * AbstractChronicleMapBuilder} documentation. * *

Functionally this interface defines some methods supporting garbage-free off-heap programming: * {@link #getUsing(Object, Object)}, {@link #acquireUsing(Object, Object)}. * *

Roughly speaking, {@code ChronicleMap} compares keys and values by their binary serialized * form, that shouldn't necessary be the same equality relation as defined by built-in {@link * Object#equals(Object)} method, which is prescribed by general {@link Map} contract. * *

Note that {@code ChronicleMap} extends {@link Closeable}, don't forget to {@linkplain #close() * close} map when it is no longer needed. * * @param the map key type * @param the map value type */ public interface ChronicleMap extends ConcurrentMap, ChronicleHash { /** * Returns the number of entries in this map. * * @return number of entries in this map * @see Map#size() */ long longSize(); /** * Returns the value to which the specified key is mapped, or {@code null} if this map contains * no mapping for the key. * *

If the value class allows reusing, particularly if it is a {@link Byteable} subclass, * consider {@link #getUsing(Object, Object)} method instead of this to reduce garbage * creation. * * @param key the key whose associated value is to be returned * @return the value to which the specified key is mapped after this method call, or {@code * null} if no value is mapped * @see #getUsing(Object, Object) */ @Override V get(Object key); /** * Returns the value to which the specified key is mapped, read to the provided {@code value} * object, if possible, or returns {@code null}, if this map contains no mapping for the key. * *

If the specified key is present in the map, the value data is read to the provided {@code * value} object via value marshaller's {@link BytesMarshaller#read(Bytes, Object) read(Bytes, * value)} or value reader's {@link BytesReader#read(Bytes, long, Object) read(Bytes, size, * value)} method, depending on what deserialization strategy is configured on the builder, * using which this map was constructed. If the value deserializer is able to reuse the given * {@code value} object, calling this method instead of {@link #get(Object)} could help to * reduce garbage creation. * *

The provided {@code value} object is allowed to be {@code null}, in this case {@code * map.getUsing(key, null)} call is semantically equivalent to simple {@code map.get(key)} * call. * * @param key the key whose associated value is to be returned * @param usingValue the object to read value data in, if possible * @return the value to which the specified key is mapped, or {@code null} if this map contains * no mapping for the key * @see #get(Object) * @see #acquireUsing(Object, Object) * @see ChronicleMapBuilder#valueMarshaller(BytesMarshaller) */ V getUsing(K key, V usingValue); /** * The method is similar {@link V getUsing(K key, V usingValue);} but in addition read locks * the map segment to operations to be performed atomically. ( see the example below ) * * Returns the ReadContext which holds a map segment lock and provides method to get the value * ( to which the specified key is mapped) atomically ( see example below for an explanation ), * read to the provided {@code value} object, if possible, or returns {@code null}, if this map * contains no mapping for the key. * *

If the specified key is present in the map, the readContext.value() uses the * provided {@code usingValue} object via value marshaller's {@link BytesMarshaller#read(Bytes, * Object) read(Bytes, value)} or value reader's {@link BytesReader#read(Bytes, long, Object) * read(Bytes, size, value)} method, depending on what deserialization strategy is configured on * the builder, using which this map was constructed. If the value deserializer is able to reuse * the given {@code usingValue} object, calling this method instead of {@link #get(Object)} * could help to reduce garbage creation. * *

try (ReadContext>?, BondVOInterface< context = map.getUsingLocked(key,using)) { * BondVOInterface bond = context.value().getValue(); * * long issueDate = bond.getIssueDate(); String symbol = bond.getSymbol(); * * // add your logic here ( the lock will ensure this bond can not be changed by another thread * ) * * } // the read lock is released here

* * To ensure that you can read the 'issueDate' and 'symbol' can be read atomically, these values * must be read while the segment lock is in place. * * *

The provided {@code value} object is allowed to be {@code null}, in this case * * @param key the key whose associated value is to be returned * @param usingValue the object to read value data in, if possible * @return the read context containing the value to which the specified key is mapped * * no mapping for the key * @see #get(Object) * @see #getUsing(Object, Object) * @see ChronicleMapBuilder#valueMarshaller(BytesMarshaller) */ @NotNull ReadContext getUsingLocked(@NotNull K key, @NotNull V usingValue); /** * Acquire a value for a key, creating if absent. * *

If the specified key if absent in the map, {@linkplain AbstractChronicleMapBuilder#defaultValue(Object) * default value} is taken or {@linkplain AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) * default value provider} is called. Then this object is put to this map for the specified * key. * *

Then, either if the key was initially absent in the map or already present, the value is * deserialized just as during {@link #getUsing(Object, Object) getUsing(key, usingValue)} call, * passed the same {@code key} and {@code usingValue} as into this method call. This means, as * in {@link #getUsing}, {@code usingValue} could safely be {@code null}, in this case a new * value instance is created to deserialize the data. * *

In code, {@code acquireUsing} is specified as

{@code
     * V acquireUsing(K key, V usingValue) {
     *     if (!containsKey(key))
     *         put(key, defaultValue(key));
     *     return getUsing(key, usingValue);
     * }}
Where {@code defaultValue(key)} returns either {@linkplain * AbstractChronicleMapBuilder#defaultValue(Object) default value} or {@link * AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) * defaultValueProvider.} * *

If the {@code ChronicleMap} is off-heap updatable, i. e. created via {@link * OffHeapUpdatableChronicleMapBuilder} builder (values are {@link Byteable}), there is one more * option of what to do if the key is absent in the map, see {@link * OffHeapUpdatableChronicleMapBuilder#prepareValueBytesOnAcquire(PrepareValueBytes)}. By * default, value bytes are just zeroed out, no default value, either provided for key or * constant, is put for the absent key. * * @param key the key whose associated value is to be returned * @param usingValue the object to read value data in, if possible * @return value to which the given key is mapping after this call, either found or created * @see #getUsing(Object, Object) */ public V acquireUsing(K key, V usingValue); @NotNull WriteContext acquireUsingLocked(@NotNull K key, @NotNull V usingValue); }