You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ab...@apache.org on 2020/09/04 14:39:39 UTC
[ignite] branch IGNITE-7595 updated: copy-paste the data strcutres
pages from readme.io
This is an automated email from the ASF dual-hosted git repository.
abudnikov pushed a commit to branch IGNITE-7595
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push:
new 1c957d6 copy-paste the data strcutres pages from readme.io
1c957d6 is described below
commit 1c957d68911d094526ae5dc360db82f48a9ad7a2
Author: abudnikov <ab...@gridgain.com>
AuthorDate: Fri Sep 4 17:38:51 2020 +0300
copy-paste the data strcutres pages from readme.io
---
.../org/apache/ignite/snippets/DataStructures.java | 206 +++++++++++++++++++++
docs/_docs/data-structures/atomic-sequence.adoc | 24 +++
docs/_docs/data-structures/atomic-types.adoc | 49 +++++
docs/_docs/data-structures/countdownlatch.adoc | 25 +++
docs/_docs/data-structures/queue-and-set.adoc | 67 +++++++
docs/_docs/data-structures/semaphore.adoc | 19 ++
6 files changed, 390 insertions(+)
diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/DataStructures.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/DataStructures.java
new file mode 100644
index 0000000..9ab882c
--- /dev/null
+++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/DataStructures.java
@@ -0,0 +1,206 @@
+package org.apache.ignite.snippets;
+
+import org.apache.ignite.Ignite;
+import org.apache.ignite.IgniteAtomicLong;
+import org.apache.ignite.IgniteAtomicReference;
+import org.apache.ignite.IgniteAtomicSequence;
+import org.apache.ignite.IgniteCountDownLatch;
+import org.apache.ignite.IgniteQueue;
+import org.apache.ignite.IgniteSemaphore;
+import org.apache.ignite.IgniteSet;
+import org.apache.ignite.Ignition;
+import org.apache.ignite.configuration.CollectionConfiguration;
+import org.junit.jupiter.api.Test;
+
+public class DataStructures {
+
+ @Test
+ void queue() {
+ //tag::queue[]
+ Ignite ignite = Ignition.start();
+
+ IgniteQueue<String> queue = ignite.queue("queueName", // Queue name.
+ 0, // Queue capacity. 0 for an unbounded queue.
+ new CollectionConfiguration() // Collection configuration.
+ );
+
+ //end::queue[]
+ ignite.close();
+ }
+
+ @Test
+ void set() {
+
+ //tag::set[]
+ Ignite ignite = Ignition.start();
+
+ IgniteSet<String> set = ignite.set("setName", // Set name.
+ new CollectionConfiguration() // Collection configuration.
+ );
+ //end::set[]
+ ignite.close();
+ }
+
+ void colocatedQueue() {
+ //tag::colocated-queue[]
+ Ignite ignite = Ignition.start();
+
+ CollectionConfiguration colCfg = new CollectionConfiguration();
+
+ colCfg.setCollocated(true);
+
+ // Create a colocated queue.
+ IgniteQueue<String> queue = ignite.queue("queueName", 0, colCfg);
+ //end::colocated-queue[]
+ ignite.close();
+ }
+
+ @Test
+ void colocatedSet() {
+ //tag::colocated-set[]
+ Ignite ignite = Ignition.start();
+
+ CollectionConfiguration colCfg = new CollectionConfiguration();
+
+ colCfg.setCollocated(true);
+
+ // Create a colocated set.
+ IgniteSet<String> set = ignite.set("setName", colCfg);
+ //end::colocated-set[]
+ ignite.close();
+ }
+
+ @Test
+ void atomicLong() {
+ //tag::atomic-long[]
+
+ Ignite ignite = Ignition.start();
+
+ IgniteAtomicLong atomicLong = ignite.atomicLong("atomicName", // Atomic long name.
+ 0, // Initial value.
+ true // Create if it does not exist.
+ );
+
+ // Increment atomic long on local node
+ System.out.println("Incremented value: " + atomicLong.incrementAndGet());
+ //end::atomic-long[]
+ ignite.close();
+ }
+
+ @Test
+ void atomicReference() {
+ //tag::atomic-reference[]
+ Ignite ignite = Ignition.start();
+
+ // Create an AtomicReference
+ IgniteAtomicReference<String> ref = ignite.atomicReference("refName", // Reference name.
+ "someVal", // Initial value for atomic reference.
+ true // Create if it does not exist.
+ );
+
+ // Compare and update the value
+ ref.compareAndSet("WRONG EXPECTED VALUE", "someNewVal"); // Won't change.
+ //end::atomic-reference[]
+ ignite.close();
+ }
+
+ @Test
+ void countDownLatch() {
+ //tag::count-down-latch[]
+ Ignite ignite = Ignition.start();
+
+ IgniteCountDownLatch latch = ignite.countDownLatch("latchName", // Latch name.
+ 10, // Initial count.
+ false, // Auto remove, when counter has reached zero.
+ true // Create if it does not exist.
+ );
+ //end::count-down-latch[]
+ ignite.close();
+ }
+
+ @Test
+ void syncOnLatch() {
+ //tag::sync-on-latch[]
+
+ Ignite ignite = Ignition.start();
+
+ final IgniteCountDownLatch latch = ignite.countDownLatch("latchName", 10, false, true);
+
+ // Execute jobs.
+ for (int i = 0; i < 10; i++)
+ // Execute a job on some remote cluster node.
+ ignite.compute().run(() -> {
+ int newCnt = latch.countDown();
+
+ System.out.println("Counted down: newCnt=" + newCnt);
+ });
+
+ // Wait for all jobs to complete.
+ latch.await();
+ //end::sync-on-latch[]
+ ignite.close();
+ }
+
+ @Test
+ void atomicSequence() {
+ //tag::atomic-sequence[]
+ Ignite ignite = Ignition.start();
+
+ //create an atomic sequence
+ IgniteAtomicSequence seq = ignite.atomicSequence("seqName", // Sequence name.
+ 0, // Initial value for sequence.
+ true // Create if it does not exist.
+ );
+
+ // Increment the atomic sequence.
+ for (int i = 0; i < 20; i++) {
+ long currentValue = seq.get();
+ long newValue = seq.incrementAndGet();
+ }
+ //end::atomic-sequence[]
+ ignite.close();
+ }
+
+ @Test
+ void semaphore() {
+ //tag::semaphore[]
+ Ignite ignite = Ignition.start();
+
+ IgniteSemaphore semaphore = ignite.semaphore("semName", // Distributed semaphore name.
+ 20, // Number of permits.
+ true, // Release acquired permits if node, that owned them, left topology.
+ true // Create if it doesn't exist.
+ );
+ //end::semaphore[]
+ ignite.close();
+ }
+
+ void useSemaphorr() {
+ //tag::use-semaphore[]
+
+ Ignite ignite = Ignition.start();
+
+ IgniteSemaphore semaphore = ignite.semaphore("semName", // Distributed semaphore name.
+ 20, // Number of permits.
+ true, // Release acquired permits if node, that owned them, left topology.
+ true // Create if it doesn't exist.
+ );
+
+ // Acquires a permit, blocking until it's available.
+ semaphore.acquire();
+
+ try {
+ // Semaphore permit is acquired. Execute a distributed task.
+ ignite.compute().run(() -> {
+ System.out.println("Executed on:" + ignite.cluster().localNode().id());
+
+ // Additional logic.
+ });
+ } finally {
+ // Releases a permit, returning it to the semaphore.
+ semaphore.release();
+ }
+
+ //end::use-semaphore[]
+ }
+}
diff --git a/docs/_docs/data-structures/atomic-sequence.adoc b/docs/_docs/data-structures/atomic-sequence.adoc
new file mode 100644
index 0000000..0ad5927
--- /dev/null
+++ b/docs/_docs/data-structures/atomic-sequence.adoc
@@ -0,0 +1,24 @@
+= Atomic Sequence
+
+:javaFile: {javaCodeDir}/DataStructures.java
+
+== Overview
+
+Distributed atomic sequence provided by `IgniteCacheAtomicSequence` interface is similar to distributed atomic long, but its value can only go up. It also supports reserving a range of values to avoid costly network trips or cache updates every time a sequence must provide a next value. That is, when you perform `incrementAndGet()` (or any other atomic operation) on an atomic sequence, the data structure reserves ahead a range of values, which are guaranteed to be unique across the clus [...]
+
+Here is an example of how atomic sequence can be created:
+
+
+[source, java]
+----
+include::{javaFile}[tags=atomic-sequence, indent=0]
+----
+
+== Sequence Reserve Size
+
+The key parameter of `IgniteAtomicSequence` is `atomicSequenceReserveSize` which is the number of sequence values reserved, per node . When a node tries to obtain an instance of `IgniteAtomicSequence`, a number of sequence values will be reserved for that node and consequent increments of sequence will happen locally without communication with other nodes, until the next reservation has to be made.
+
+The default value for `atomicSequenceReserveSize` is `1000`. This default setting can be changed by modifying the `atomicSequenceReserveSize` property of `AtomicConfiguration`.
+
+Refer to link:atomic-types#atomic-configuration[Atomic Configuration] for more information on various atomic configuration properties.
+
diff --git a/docs/_docs/data-structures/atomic-types.adoc b/docs/_docs/data-structures/atomic-types.adoc
new file mode 100644
index 0000000..b6d72b6
--- /dev/null
+++ b/docs/_docs/data-structures/atomic-types.adoc
@@ -0,0 +1,49 @@
+= Atomic Types
+
+:javaFile: {javaCodeDir}/DataStructures.java
+
+Ignite supports distributed atomic long and atomic reference, similar to `java.util.concurrent.atomic.AtomicLong` and `java.util.concurrent.atomic.AtomicReference` respectively.
+
+Atomics in Ignite are distributed across the cluster, essentially enabling performing atomic operations (such as increment-and-get or compare-and-set) with the same globally-visible value. For example, you could update the value of an atomic long on one node and read it from another node.
+
+Features:
+
+ * Retrieve current value.
+ * Atomically modify current value.
+ * Atomically increment or decrement current value.
+ * Atomically compare-and-set the current value to new value.
+
+Distributed atomic long and atomic reference can be obtained via `IgniteAtomicLong` and `IgniteAtomicReference` interfaces respectively, as shown below:
+
+
+
+.AtomicLong:
+[source, java]
+----
+include::{javaFile}[tags=atomic-long, indent=0]
+----
+
+.AtomicReference:
+[source, java]
+----
+include::{javaFile}[tags=atomic-reference, indent=0]
+----
+
+All atomic operations provided by `IgniteAtomicLong` and `IgniteAtomicReference` are synchronous. The time an atomic operation will take depends on the number of nodes performing concurrent operations with the same instance of atomic long, the intensity of these operations, and network latency.
+
+
+== Atomic Configuration
+
+Atomics in Ignite can be configured via the `atomicConfiguration` property of `IgniteConfiguration`.
+
+The following table lists available configuration parameters:
+
+[cols="1,1,1",opts="header"]
+|===
+| Setter | Description | Default
+| `setBackups(int)` | The number of backups. | 0
+| `setCacheMode(CacheMode)` | Cache mode for all atomic types. | `PARTITIONED`
+| `setAtomicSequenceReserveSize(int)` | Sets the number of sequence values reserved for `IgniteAtomicSequence` instances. | 1000
+|===
+
+
diff --git a/docs/_docs/data-structures/countdownlatch.adoc b/docs/_docs/data-structures/countdownlatch.adoc
new file mode 100644
index 0000000..e6dccc0
--- /dev/null
+++ b/docs/_docs/data-structures/countdownlatch.adoc
@@ -0,0 +1,25 @@
+= CountDownLatch
+
+:javaFile: {javaCodeDir}/DataStructures.java
+
+`IgniteCountDownLatch` provides functionality that is similar to that of `java.util.concurrent.CountDownLatch` and allows you to synchronize operations accross cluster nodes.
+
+A distributed CountDownLatch can be created as follows:
+
+[source, java]
+----
+include::{javaFile}[tags=count-down-latch, indent=0]
+----
+
+
+After the above code is executed, all nodes in the specified cache will be able to synchronize on the latch named `latchName`.
+Below is a code example of such synchronization:
+
+
+[source, java]
+----
+include::{javaFile}[tags=sync-on-latch, indent=0]
+
+----
+
+
diff --git a/docs/_docs/data-structures/queue-and-set.adoc b/docs/_docs/data-structures/queue-and-set.adoc
new file mode 100644
index 0000000..b000406
--- /dev/null
+++ b/docs/_docs/data-structures/queue-and-set.adoc
@@ -0,0 +1,67 @@
+= Queue and Set
+:javaFile: {javaCodeDir}/DataStructures.java
+== Overview
+
+In addition to providing standard key-value map-like storage, Ignite also provides an implementation of a fast Distributed Blocking Queue and Distributed Set.
+
+`IgniteQueue` and `IgniteSet`, an implementation of `java.util.concurrent.BlockingQueue` and `java.util.Set` interface respectively, also support all operations from the `java.util.Collection` interface.
+Both types can be created in either collocated or non-collocated mode.
+
+Below is an example of how to create a distributed queue and set.
+
+.Queue:
+[source, java]
+----
+include::{javaFile}[tags=queue, indent=0]
+----
+
+
+.Set:
+[source, java]
+----
+include::{javaFile}[tags=set, indent=0]
+----
+
+== Collocated vs. Non-Collocated Mode
+
+If you plan to create just a few queues or sets containing lots of data, then you would create them in non-collocated mode. This will make sure that about equal portion of each queue or set will be stored on each cluster node. On the other hand, if you plan to have many queues or sets, relatively small in size (compared to the whole cache), then you would most likely create them in collocated mode. In this mode all queue or set elements will be stored on the same cluster node, but about [...]
+
+Non-collocated mode only makes sense for and is only supported for `PARTITIONED` caches.
+
+A collocated queue and set can be created by setting the `collocated` property of `CollectionConfiguration`, like so:
+
+.Queue:
+[source, java]
+----
+include::{javaFile}[tags=colocated-queue, indent=0]
+----
+
+
+.Set:
+[source, java]
+----
+include::{javaFile}[tags=colocated-set, indent=0]
+----
+
+== Cache Queues and Load Balancing
+
+Given that elements will remain in the queue until someone takes them, and that no two nodes should ever receive the same element from the queue, cache queues can be used as an alternate work distribution and load balancing approach within Ignite.
+
+For example, you could simply add computations, such as instances of `IgniteRunnable` to a queue, and have threads on remote nodes call `IgniteQueue.take()` method which will block if queue is empty. Once the `take()` method will return a job, a thread will process it and call `take()` again to get the next job. Given this approach, threads on remote nodes will only start working on the next job when they have completed the previous one, hence creating ideally balanced system where ever [...]
+
+== Collection Configuration
+
+Ignite collections can be in configured in API via `CollectionConfiguration` (see above examples). The following configuration parameters can be used:
+
+
+
+[cols="1,1,1",opts="header"]
+|===
+| Setter | Description | Default
+| `setCollocated(boolean)` | Sets collocation mode. | `false`
+|`setCacheMode(CacheMode)` | Sets underlying cache mode (`PARTITIONED`, `REPLICATED` or `LOCAL`). | `PARTITIONED`
+| `setAtomicityMode(CacheAtomicityMode)` | Sets underlying cache atomicity mode (`ATOMIC` or `TRANSACTIONAL`). | `ATOMIC`
+| `setOffHeapMaxMemory(long)` | Sets offheap maximum memory size. | `0` (unlimited)
+| `setBackups(int)` | Sets number of backups. | `0`
+|`setNodeFilter(IgnitePredicate<ClusterNode>)` | Sets optional predicate specifying on which nodes entries should be stored. |
+|===
diff --git a/docs/_docs/data-structures/semaphore.adoc b/docs/_docs/data-structures/semaphore.adoc
new file mode 100644
index 0000000..614d5f2
--- /dev/null
+++ b/docs/_docs/data-structures/semaphore.adoc
@@ -0,0 +1,19 @@
+= Semaphore
+
+:javaFile: {javaCodeDir}/DataStructures.java
+
+Ignite's counting distributed semaphore implementation and behavior is similar to the concept of a well-known `java.util.concurrent.Semaphore`. As any other semaphore it maintains a set of permits that are taken using `acquire()` method and released with `release()` counterpart allowing to restrict access to some logical or physical resource or synchronize execution flow. The only difference is that Ignite's semaphore empowers you to fulfill these kind of actions not only in boundaries o [...]
+
+You can create a distributed semaphore as follows:
+[source, java]
+----
+include::{javaFile}[tags=semaphore, indent=0]
+----
+
+Once the semaphore is created, it can be used concurrently by multiple cluster nodes in order to implement some distributed logic or restrict access to a distributed resource like in the following example:
+
+[source, java]
+----
+include::{javaFile}[tags=use-semaphore, indent=0]
+----
+