+Different memory types can have different performance characteristics. They +can be distinguished by values of their latency, capacity, or bandwidth. +In programming with allocation tiering in mind we care about the performance +characteristics of memory, not the exact media types. +
+In this example, an array of data and a hashmap are allocated to different +memory types to effectively use the available memory. + +{{template "scrollToContinue"}} + +
+When utilising a server with high capacity memory alongside standard memory, +allocating memory randomly in two types of memory which have different +performance characteristics might not be a good idea. Typically, a memory +with high capacity have higher latency than standard memory. Because of that, +the application may benefit from having some data allocated explicitly on +memory with low latency. On the other hand, to utilise the whole available +memory capacity in a server, we might allocate specific data always in +a high capacity memory. +
+In this example, allocations of an array of data and a hashtable for accessing
+that data are made with the usage of the memkind library. Splitting
+allocations between a low latency memory and a high capacity memory is achieved
+by utlising two kinds (you can think of them as an additional parameter to
+malloc()): MEMKIND_LOWEST_LATENCY_LOCAL and
+MEMKIND_HIGHEST_CAPACITY.
+It's reasonable to have a reliably fast access to the hashtable. Also searching
+for data might benefit from keys being allocated in a low latency memory.
+To achieve this, the MEMKIND_LOWEST_LATENCY_LOCAL kind is used for
+allocating the hashtable and data keys.
+The memory with the lowest latency be allocated.
+Data that is being accessed from the hashtable have bigger size relative to
+a key size. Because of that, that data is a perfect fit for utilising the
+advantage of high capacity media. MEMKIND_HIGHEST_CAPACITY kind allows to
+explicitly allocate memory from this memory type.
+
+{{step "Using memkind for allocations based on memory characteristics"}}
+
+
+This program allocates hashmap, keys, and data using different memory
+characteristics for explicit allocations on specific media types.
+Note that functions highest_capacity_malloc() and
+lowest_latency_malloc() are wrappers for allocating with the usage
+of memkind and kinds based on performance characteristics retrieved from
+the hwloc library (memkind's dependency).
+
+Complete hashmap implementation is in hashmap.c file (and a respective header +file). + +{{edit "hmat.c" "hashmap.c" "hashmap.h" "Makefile"}} + +
+Click the button below to build the program. + +{{build "make"}} + +If the program compiled without errors, run the example by clicking +the button below: + +{{run "./run.sh"}} + +{{summary}} + +
+This example shows how memkind can be useful in programming based on the media
+characteristics. Developer doesn't have to know what setup is available on
+the machine the code is running on. In fact, the code will work when the only
+memory type available is DRAM, too. One may see these memkind kinds as a hint
+for the allocator as to whether allocated data should have fast access, huge
+storage or (not used in this example) fast bandwidth. You can also play with
+other memkind kinds listed
+here.
+
+{{bottom}}
diff --git a/templates/examples/I/description.tmpl b/templates/examples/I/description.tmpl
new file mode 100644
index 0000000..fbf09d7
--- /dev/null
+++ b/templates/examples/I/description.tmpl
@@ -0,0 +1,12 @@
+{{template "tocEntryStart" .}}
+{{template "tocShortText" .}}
+Allocation tiering based on memory-characteristics
+{{template "tocLongText" .}}
+{{template "tocRecommended" .}}
+This example shows allocation tiering with the usage of memkind.
+This is achieved by utilising memory performance characteristics provided by
+kernel and the libhwloc library. Allocation tiering is based on
+the lowest latency and the highest capacity tiers.
+
+This example is intended for C programmers.
+{{template "tocEntryEnd" .}}