{"id":20038552,"url":"https://github.com/yahoo/oak","last_synced_at":"2025-04-05T17:09:44.499Z","repository":{"id":41176219,"uuid":"140631483","full_name":"yahoo/Oak","owner":"yahoo","description":"A Scalable Concurrent Key-Value Map for Big Data Analytics","archived":false,"fork":false,"pushed_at":"2024-01-18T20:15:03.000Z","size":2060,"stargazers_count":270,"open_issues_count":37,"forks_count":46,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-29T16:10:05.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"Code-of-Conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-11T21:57:20.000Z","updated_at":"2025-02-06T13:59:50.000Z","dependencies_parsed_at":"2022-09-03T12:00:22.934Z","dependency_job_id":"a32b44b6-4b64-46af-85cf-542a0c0bac4c","html_url":"https://github.com/yahoo/Oak","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2FOak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2FOak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2FOak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2FOak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/Oak/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369953,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T10:29:57.696Z","updated_at":"2025-04-05T17:09:44.471Z","avatar_url":"https://github.com/yahoo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oak\n\u003e Oak (Off-heap Allocated Keys) is a scalable, concurrent, in-memory Key-Value (KV) map.\n\nOakMap is a concurrent Key-Value Map that keeps all keys and values off-heap. This allows storing more data (up to 3 times more data) compare to using the standard JVM heap management, albeit using the same memory footprint.\nOakMap implements the industry-standard Java8 ConcurrentNavigableMap API. It provides strong (atomic) semantics for read, write, and read-modify-write operations, as well as (non-atomic) range query (scan) operations, both forward and backward.\nOakMap is optimized for big keys and values, in particular, for incremental maintenance of objects (update in-place).\nIt is faster and scales better with additional CPU cores than the popular Java ConcurrentNavigableMap [ConcurrentSkipListMap](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ConcurrentSkipListMap.html).\n\n## Why OakMap?\n1. OakMap provides great performance: it employs fine-grain synchronization, and thus scales well with numbers of threads; it also achieves cache-friendliness by avoiding memory fragmentation (see [performance evaluation](https://github.com/yahoo/Oak/wiki/Performance)).\n2. OakMap takes keys and the data off-heap, and thus allows working with a huge heap (RAM) -- even more than 50G -- without JVM GC overheads.\n   - To support off-heap, OakMap has embedded, efficient, epoch-based memory management that mostly eliminates JVM GC overheads.\n4. OakMap provides a rich API for **atomic** accesses to data. For example, OakMap supports atomic compute() -- in place computations on existing keys -- whereas the current Java ConcurrentSkipListMap implementation does not guarantee the atomicity of `compute()`. OakMap’s update operations (such as put and compute) take user-provided lambda functions for easy integration in diverse use cases.\n5. Descending Scans: OakMap expedites descending scans without additional complexity. In our experiments, OakMap’s descending scans are 4.8x faster than ConcurrentSkipListMap’s, and perform similarly to their ascending counterparts (see [performance evaluation](https://github.com/yahoo/Oak/wiki/Performance-Evaluation)).\n\n## Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Builder](#builder)\n- [API](#api)\n- [Usage](#usage)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Background\n\n### Design Points\n- OakMap consists of an on-heap index to off-heap keys and values. OakMap's index is structured as a list of contiguous chunks of memory; this speeds up searches through the index due to access locality and cache-friendliness. Read more about [OakMap design](https://github.com/yahoo/Oak/wiki/Design).\n- OakMap's keys and values are copied and stored in self-managed off-heap byte arrays.\n\n### Design Requirements\nTo efficiently manage its content, OakMap requires that the user define two auxiliary tools: an OakSerializer and an OakComparator; both are passed during construction.\n1. *OakSerializer:* Both keys and values need to provide a (1) serializer, (2) deserializer, and (3) serialized size calculator. All three are parts of [OakSerializer](#oakserializer).\n   - For boosting performance, OakMap allocates space for a given key/value and then uses the given serializer to write the key/value directly to the allocated space. OakMap uses the appropriate size calculator to deduce the amount of space to be allocated. Note that both keys and values are variable-sized.\n2. *OakComparator:* To compare the internally-kept serialized keys with the deserialized key provided by the API, OakMap requires a (key) comparator. The comparator compares two keys, each of which may be provided either as a deserialized object or as a serialized one, determining whether they are equal, and if not, which is bigger.\n\n## Install\nOakMap is a library. After downloading Oak, compile it using `mvn install package` to compile and install. Then update your project's pom.xml file dependencies, as follows:\n```xml\n  \u003cdependency\u003e\n      \u003cgroupId\u003eoak\u003c/groupId\u003e\n      \u003cartifactId\u003eoak\u003c/artifactId\u003e\n      \u003cversion\u003e1.0-SNAPSHOT\u003c/version\u003e\n  \u003c/dependency\u003e\n```\nFinally, import the relevant classes and use OakMap according to the description below.\n\n## Builder\n\nTo build `OakMap`, the user should first create the builder, and then use it to construct `OakMap`:\n```java\nOakMapBuilder\u003cK,V\u003e builder = ... // create a builder; details provided below\nOakMap\u003cK,V\u003e oak = builder.build();\n```\n\nOakMap requires multiple parameters to be defined for the builder, as shall be explained below.\nWhen constructing off-heap OakMap, the memory capacity (per OakMap instance) needs to be specified. OakMap allocates the off-heap memory with the requested capacity at construction time and later manages this memory.\n\n### OakSerializer\nAs explained above, `OakMap\u003cK, V\u003e` is given key `K` and value `V`, which are requested to come with a serializer, deserializer, and size calculator. OakMap user needs to implement the following interface that can be found in the Oak project.\n\n```java\npublic interface OakSerializer\u003cT\u003e {\n  // serializes the data\n  void serialize(T data, OakScopedWriteBuffer serializedData);\n\n  // deserializes the data\n  T deserialize(OakScopedReadBuffer serializedData);\n\n  // returns the number of bytes needed for serializing the given data\n  int calculateSize(T data);\n}\n```\n\n*Note 1*: Oak use dedicated objects to access off-heap memory: `OakScopedReadBuffer` and `OakScopedWriteBuffer`.\nSee [Oak Buffers](#oak-buffers) for more information.\n\n*Note 2*: `OakScopedReadBuffer` and `OakScopedWriteBuffer` should not be stored for future use.\nThey are valid only in the context of these methods (`serialize()`/`deserialize()`).\nUsing these buffers outside their intended context may yield unpredicted results.\n\nFor example, the implementation of key serializer for an application that use integer as keys might look like this:\n\n```java\npublic class MyAppKeySerializer implements OakSerializer\u003cInteger\u003e {\n  void serialize(Integer key, OakScopedWriteBuffer serializedKey) {\n    // We store the value at the first position of the off-heap buffer.\n    serializedKey.putInt(0, value);\n  }\n    \n  Integer deserialize(OakScopedReadBuffer serializedKey) {\n    return serializedKey.getInt(0);\n  }\n    \n  int calculateSize(Integer key) {\n    // We only store one integer\n    return Integer.BYTES;\n  }\n}\n\npublic class MayAppValueSerializer implements OakSerializer\u003cV\u003e\n{...}\n```\n\n### Minimal Key\nOakMap requires a minimal key that can represent negative infinity according to the user-defined comparison among the keys. The requested minimal key is of type `K` and is considered by the given comparator to be smaller than every other key (serialized or not). The minimal key is passed as a parameter during builder creation.\n\n### Comparator\nAfter a Key-Value pair is inserted into OakMap, it is kept in a serialized (buffered) state. However, OakMap's API gets the input key as an object, the serialization of which is deferred until it proves to be required.\nThus, while searching through the map, OakMap might compare between two keys in their Object and Serialized modes. OakMap provides the following interface for such a comparator:\n```java\npublic interface OakComparator\u003cK\u003e {\n  int compareKeys(K key1, K key2);\n\n  int compareSerializedKeys(OakScopedReadBuffer serializedKey1, OakScopedReadBuffer serializedKey2);\n\n  int compareSerializedKeyAndKey(OakScopedReadBuffer serializedKey1, K key2);\n}\n```\n\n*Note 1*: Oak use dedicated objects to access off-heap memory: `OakScopedReadBuffer` and `OakScopedWriteBuffer`.\nSee [Oak Buffers](#oak-buffers) for more information.\n\n*Note 2*: `OakScopedReadBuffer` and `OakScopedWriteBuffer` should not be stored for future use.\nThey are valid only in the context of these methods (`compareKeys()`/`compareSerializedKeys()/compareSerializedKeyAndKey()`).\nUsing these buffers outside their intended context may yield unpredicted results.\n\nFor example, the implementation of a key comparator for an application that uses integer as keys might look like this:\n\n```java\npublic class MyAppKeyComparator implements OakComparator\u003cInteger\u003e\n{\n  int compareKeys(Integer key1, Integer key2) {\n    return Integer.compare(key1, key2);\n  }\n\n  int compareSerializedKeys(OakReadBuffer serializedKey1, OakReadBuffer serializedKey2) {\n    return Integer.compare(serializedKey1.getInt(0), serializedKey2.getInt(0)); \n  }\n\n  int compareSerializedKeyAndKey(OakReadBuffer serializedKey1, Integer key2) {\n    return Integer.compare(serializedKey1.getInt(0), key2);\n  }\n}\n```\n\n### Builder\nWe provide an example of how to create OakMapBuilder and OakMap. For a more comprehensive code example please refer to the [Usage](#usage) section.\n\n```java\nOakMapBuilder\u003cK,V\u003e builder = new OakMapBuilder()\n            .setKeySerializer(new MyAppKeySerializer())\n            .setValueSerializer(new MyAppValueSerializer())\n            .setMinKey(...)\n            .setKeysComparator(new MyAppKeyComparator())\n            .setMemoryCapacity(...);\n\nOakMap\u003cK,V\u003e oak = builder.build();\n```\n\n## API\n\n### OakMap Methods\nOakMap's API implements the ConcurrentNavigableMap interface. For improved performance, it offers additional non-standard zero-copy API methods that are discussed below.\n\nYou are welcome to take a look at the OakMap's [full API](https://github.com/yahoo/Oak/wiki/Full-API).\nFor a more comprehensive code example please refer to the [usage](#usage) section. \n\n### Oak Buffers\nOak uses dedicated buffer objects to access off-heap memory. \nThese buffers cannot be instantiated by the user and are always supplied to the user by Oak.\nTheir interfaces are:\n\u003cpre\u003e\nBuffer                    Access      Usage\n------------------------  ----------  ------------------------------\n\u003ca href=\"./core/src/main/java/com/yahoo/oak/OakBuffer.java\" title=\"OakBuffer\"\u003eOakBuffer\u003c/a\u003e                 read-only   base class for all the buffers\n├── \u003ca href=\"./core/src/main/java/com/yahoo/oak/OakScopedReadBuffer.java\" title=\"OakScopedReadBuffer\"\u003eOakScopedReadBuffer\u003c/a\u003e   read-only   attached to a specific scope\n├── \u003ca href=\"./core/src/main/java/com/yahoo/oak/OakScopedWriteBuffer.java\" title=\"OakScopedWriteBuffer\"\u003eOakScopedWriteBuffer\u003c/a\u003e  read/write  attached to a specific scope\n└── \u003ca href=\"./core/src/main/java/com/yahoo/oak/OakUnscopedBuffer.java\" title=\"OakUnscopedBuffer\"\u003eOakUnscopedBuffer\u003c/a\u003e     read-only   can be used in any scope\n\u003c/pre\u003e\n\nThese buffers may represent either a key or a value.\nThey mimic the standard interface of Java's `ByteBuffer`, for example, `int getInt(int index)`, `char getChar(int index)`, `capacity()`, etc. \n\nThe scoped buffers (`OakScopedReadBuffer` and `OakScopedWriteBuffer`) are attached to the scope of the callback method they were first introduced to the user. The behavior of these buffers outside their attached scope is undefined.\nSuch a callback method might be the application's serializer and comparator, or a lambda function that can read/store/update the data.\nThis access reduces unnecessary copies and deserialization of the underlying data.\nIn their intended context, the user does not need to worry about concurrent accesses and memory management.\nUsing these buffers outside their intended context may yield unpredicted results, e.g., reading non-consistent data and/or irrelevant data.\n\nThe un-scoped buffer (`OakUnscopedBuffer`) is detached from any specific scope, i.e., it may be stored for future use.\nThe zero-copy methods of `OakMap` return this buffer to avoid copying the data and instead the user can access the underlying memory buffer directly (lazy evaluation).\nWhile the scoped buffers' data accesses are synchronized, when using `OakUnscopedBuffer`, the same memory might be access by concurrent update operations.\nThus, the reader may encounter different values -- and even value deletions -- when accessing `OakUnscopedBuffer` multiple times.\nSpecifically, when trying to access a deleted mapping via an `OakUnscopedBuffer`, `ConcurrentModificationException` will be thrown.\nThis is of course normal behavior for a concurrent map that avoids copying.\nTo allow complex, multi-value atomic operations on the data, `OakUnscopedBuffer` provides a `transform()` method that allows the user to apply a transformation function atomically on a read-only, scoped version of the buffer (`OakScopedReadBuffer`). \nSee the [Data Retrieval](#data-retrieval) for more information.\n\nFor performance and backward compatibility with applications that are already based on the use of `ByteBuffer`, Oak's buffers also implement a dedicated unsafe interface `OakUnsafeDirectBuffer`.\nThis interface allows high-performance access to the underlying data of Oak.\nTo achieve that, it sacrifices safety, so it should be used only if you know what you are doing.\nMisuse of this interface might result in corrupted data, a crash or a deadlock.\n\nSpecifically, the developer should be concerned with two issues:\n 1. _Concurrency_: using this interface inside the context of `serialize()`, `compute(), `compare()` and `transform()` is thread-safe.\n    In other contexts (e.g., `get()` output), the developer should ensure that there is no concurrent access to this data. Failing to ensure that might result in corrupted data.\n 2. _Data boundaries_: when using this interface, Oak will not alert the developer regarding any out of boundary access.\n    Thus, the developer should use `getOffset()` and `getLength()` to obtain the data boundaries and carefully access the data. Writing data out of these boundaries might result in corrupted data, a crash, or a deadlock.\n\nTo use this interface, the developer should cast Oak's buffer (`OakScopedReadBuffer` or `OakScopedWriteBuffer`) to this interface,\nsimilarly to how Java's internal DirectBuffer is used. For example:\n```java\nint foo(OakScopedReadBuffer b) {\n  OakUnsafeDirectBuffer ub = (OakUnsafeDirectBuffer) b;\n  ByteBuffer bb = ub.getByteBuffer();\n  return bb.getInt(ub.getOffset());\n}\n```\n\n*Note 1*: in the above example, the following will throw a `ReadOnlyBufferException` because the buffer mode is read-only:\n```java\nbb.putInt(ub.getOffset(), someInteger);\n```\n\n*Note 2*: the user should never change the buffer's state, namely the position and limit (`bb.limit(i)` or `bb.position(i)`).\nChanging the buffer's state will make some data inaccessible to the user in the future.   \n\n\n### Data Retrieval\n1. For best performance of data retrieval, `OakMap` supplies a `ZeroCopyMap` interface of the map:\n    `ZeroCopyMap\u003cK, V\u003e zc()` \n    \n    The `ZeroCopyMap` interface provides the following four methods for data retrieval, whose result is presented as an `OakUnscopedBuffer`:\n   - `OakUnscopedBuffer get(K key)`\n   - `Collection\u003cOakUnscopedBuffer\u003e values()`\n   - `Set\u003cMap.Entry\u003cOakUnscopedBuffer, OakUnscopedBuffer\u003e\u003e entrySet()`\n   - `Set\u003cOakUnscopedBuffer\u003e keySet()`\n    - `Set\u003cOakUnscopedBuffer\u003e keyStreamSet()`\n    - `Collection\u003cOakUnscopedBuffer\u003e valuesStream()`\n    - `Set\u003cMap.Entry\u003cOakUnscopedBuffer, OakUnscopedBuffer\u003e\u003e entryStreamSet()`\n   \n    Note that in addition to the `ConcurrentNavigableMap` style sets, we introduce a new type of stream sets.\n    When a stream-set is iterated it gives a \"stream\" view of the elements, meaning only one element can be observed at a time.\n    It is preferred to use the stream iterators when possible as they instantiate significantly fewer objects, which improve performance. \n2. Without `ZeroCopyMap`, `OakMap`'s data can be directly retrieved via the following four methods:\n   - `V get(Object key)`\n   - `Collection\u003cV\u003e values()`\n   - `Set\u003cMap.Entry\u003cK, V\u003e\u003e entrySet()`\n   - `NavigableSet\u003cK\u003e keySet()`\n   \n   However, these direct methods return keys and/or values as Objects by applying deserialization (copy). This is costly, and we strongly advise to use `ZeroCopyMap` to operate directly on the internal data representation.\n3. For examples of direct data manipulations, please refer to the [usage](#usage) section.\n\n### Data Ingestion\n1. Data can be ingested via the standard `ConcurrentNavigableMap` API.\n2. For improved performance, data can be also ingested and updated via the following five methods provided by the `ZeroCopyMap` interface:\n   - `void put(K key, V value)`\n   - `boolean putIfAbsent(K key, V value)`\n   - `void remove(K key)`\n   - `boolean computeIfPresent(K key, Consumer\u003cOakScopedWriteBuffer\u003e computer)`\n   - `boolean putIfAbsentComputeIfPresent(K key, V value, Consumer\u003cOakScopedWriteBuffer\u003e computer)`\n3. In contrast to the `ConcurrentNavigableMap` API, the zero-copy method `void put(K key, V value)` does not return the value previously associated with the key, if key existed. Likewise, `void remove(K key)` does not return a boolean indicating whether key was actually deleted, if key existed.\n4. `boolean computeIfPresent(K key, Consumer\u003cOakScopedWriteBuffer\u003e computer)` gets the user-defined computer function. The computer is invoked in case the key exists.\nThe computer is provided with a mutable `OakScopedWriteBuffer`, representing the serialized value associated with the key. The computer's effect is atomic, meaning either all updates are seen by concurrent readers, or none are.\nThe `compute()` functionality offers the `OakMap` user an efficient zero-copy update-in-place, which allows `OakMap` users to focus on business logic without dealing with the hard problems that data layout and concurrency control present.\n5. Additionally, `OakMap` supports an atomic `boolean putIfAbsentComputeIfPresent(K key, V value, Consumer\u003cOakScopedWriteBuffer\u003e computer)` interface, (which is not part of `ConcurrentNavigableMap`).\nThis API looks for a key. If the key does not exist, it adds a new Serialized key --\u003e Serialized value mapping. Otherwise, the value associated with the key is updated with `computer(old value)`. This interface works concurrently with other updates and requires only one search traversal. This interface returns true if a new key was added, false otherwise.\n\n## Memory Management\nAs explained above, when constructing off-heap `OakMap`, the memory capacity (per `OakMap` instance) needs to be specified. `OakMap` allocates the off-heap memory with the requested capacity at construction time, and later manages this memory.\nThis memory (the entire given capacity) needs to be released later, thus `OakMap` implements `AutoClosable`. Be sure to use it within try-statement or better invoke `OakMap.close()` method when `OakMap` is no longer in use.\n\nPlease pay attention that multiple Oak sub-maps can reference the same underlying memory of `OakMap`. The memory will be released only when the last of those sub-maps are closed.\nHowever, note that each sub-map is in particular an `OakMap` and thus `AutoCloseable` and needs to be closed (explicitly or implicitly). Again, `close()` can be invoked on different objects referring to the same underlying memory, but the final release will happen only once.\n\n## Usage\n\nAn Integer to Integer build example can be seen in [Code Examples](https://github.com/yahoo/Oak/wiki/Code-Examples). Here we illustrate individual operations.\n\n### Code Examples\n\nWe show some examples of Oak `ZeroCopyMap` interface usage below. These examples assume `OakMap\u003cInteger, Integer\u003e oak` is defined and constructed as described in the [Builder](#builder) section.\n\n##### Simple Put and Get\n```java\noak.put(10,100);\nInteger i = oak.get(10);\n```\n\n##### Remove\n```java\noak.zc().remove(11);\n```\n\n##### Get OakUnscopedBuffer\n```java\nOakUnscopedBuffer buffer = oak.zc().get(10);\nif(buffer != null) {\n    try {\n        int get = buffer.getInt(0);\n    } catch (ConcurrentModificationException e) {\n    }\n}\n```\n\n##### Scan \u0026 Copy\n```java\nInteger[] targetBuffer = new Integer[oak.size()]; // might not be correct with multiple threads\nIterator\u003cInteger\u003e iter = oak.values().iterator();\nint i = 0;\nwhile (iter.hasNext()) {\n    targetBuffer[i++] = iter.next();\n}\n```\n\n##### Compute\n```java\nConsumer\u003cOakScopedWriteBuffer\u003e func = buf -\u003e {\n    Integer cnt = buf.getInt(0);   // read integer from position 0\n    buf.putInt(0, (cnt+1));        // accumulate counter, position back to 0\n};\noak.zc().computeIfPresent(10, func);\n```\n\n##### Conditional Compute\n```java\nConsumer\u003cOakScopedWriteBuffer\u003e func = buf -\u003e {\n    if (buf.getInt(0) == 0) {     // check integer at position 0\n        buf.putInt(1);             // position in the buffer is promoted\n        buf.putInt(1);\n    }\n};\noak.zc().computeIfPresent(10, func);\n```\n\n##### Simple Iterator\n```java\nIterator\u003cInteger\u003e iterator = oak.keySet().iterator();\nwhile (iter.hasNext()) {\n    Integer i = iter.next();\n}\n```\n\n##### Simple Descending Iterator\n```java\ntry (OakMap\u003cInteger, Integer\u003e oakDesc = oak.descendingMap()) {\n    Iterator\u003cInteger, Integer\u003e\u003e iter = oakDesc.entrySet().iterator();\n    while (iter.hasNext()) {\n        Map.Entry\u003cInteger, Integer\u003e e = iter.next();\n    }\n}\n```\n\n##### Simple Range Iterator\n```java\nInteger from = (Integer)4;\nInteger to = (Integer)6;\n\ntry (OakMap sub = oak.subMap(from, false, to, true)) {\n    Iterator\u003cInteger\u003e  iter = sub.values().iterator();\n    while (iter.hasNext()) {\n        Integer i = iter.next();\n    }\n}\n```\n\n##### Transformations\n\n```java\nFunction\u003cOakScopedReadBuffer, String\u003e intToStrings = e -\u003e String.valueOf(e.getInt(0));\n\nIterator\u003cString\u003e iter = oak.zc().values().stream().map(v -\u003e v.transform(intToStrings)).iterator();\nwhile (iter.hasNext()) {\n    String s = iter.next();\n}\n```\n\n##### Unsafe buffer access\n\n```java\nFunction\u003cOakScopedReadBuffer, String\u003e intToStringsDirect = b -\u003e {\n  OakUnsafeDirectBuffer ub = (OakUnsafeDirectBuffer) b;\n  ByteBuffer bb = ub.getByteBuffer();\n  return bb.getInt(ub.getOffset());\n};\n\nIterator\u003cString\u003e iter = oak.zc().values().stream().map(v -\u003e v.transform(intToStringsDirect)).iterator();\nwhile (iter.hasNext()) {\n    String s = iter.next();\n}\n```\n\n##### Unsafe direct buffer access (address)\nOak support accessing its keys/values using direct memory address.\n`DirectUtils` can be used to access the memory address data.\n\n```java\nFunction\u003cOakScopedReadBuffer, String\u003e intToStringsDirect = b -\u003e {\n  OakUnsafeDirectBuffer ub = (OakUnsafeDirectBuffer) b;\n  return DirectUtils.getInt(ub.getAddress());\n};\n\nIterator\u003cString\u003e iter = oak.zc().values().stream().map(v -\u003e v.transform(intToStringsDirect)).iterator();\nwhile (iter.hasNext()) {\n    String s = iter.next();\n}\n```\n\nNote: in the above example, the following will not throw any exception even if the buffer mode is read-only:\n```java\nDirectUtils.putInt(ub.getAddress(), someInteger);\n```\n\n## Contribute\n\nPlease refer to the [contributing file](./CONTRIBUTING.md) for information about how to get involved. We welcome issues, questions, and pull requests.  \n\n\n## License\n\nThis project is licensed under the terms of the [Apache 2.0](LICENSE-Apache-2.0) open source license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Foak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Foak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Foak/lists"}