Glossary.md

@@ -9,9 +9,6 @@ A application programming interface facilitates the interaction between differen
 # Benchmarking
 The act of collecting data to compare things. Linktest benchmarks communication APIs and the associated hardware by measuring how long it takes for a message to be sent back-and-forth between two tasks, which allows for the comparison to the time it takes the same message to be sent back-and-forth between a different pair of tasks or using a different communication API.
 
-# Mode
-The `--mode` command-line option defines which communication API Linktest benchmarks. As a shorthand `-m` can be used. See [Communication API](#communication-api) for a list of supported communication APIs.
-
 # Bidirectional Testing
 Not to be confused with bisection testing. In bidirectional testing messages are sent between tasks asynchronously. Normally Linktest benchmarks communication times by sending a message from one task in pair to the other and then the other sends the same message back. In bidirectional testing both tasks send messages to each other at the same time. This means that neither task weights on the other before sending their message. Such communication is more taxing between two tasks but also commonly faster because neither task has to wait on the other before send their message. Bisection testing can be turned on by specifying the `--bisection` command-line option.
 
@@ -20,6 +17,12 @@ Not to be confused with bidirectional testing. In bisection communication testin
 
 Please note that the sets are determined at beginning of testing and are never changed. As such a given configuration always results in the same split of tasks into halves. If you wish to have different tasks associated with the two different halves then the task order needs to be changed. This is ideally done when submitting the parallel job for Linktest.
 
+# Buffer Randomization
+Linktest has the ability to randomize buffers before transferring them. As some new communication APIs compress messages on the fly this option is there to ensure that the actual time it takes to transfer the messages can be measured, not the time it takes for a compressed version of the message to be sent.
+
+# Checking Memory-Buffer Content
+Linktest has the ability to check its buffers after a connection has been tested, this is to ensure that the correct information has been transferred, i.e. that the communication API transferred the correct buffer to the receiver and did not modify the sending buffer. This is done by iteratively going through the buffer and checking each byte.
+
 # Communication API
 Communication APIs facilitate the communication between different computers by abstracting the underlying necessary hardware commands into easy-to-use portable instructions that can work on a host of different machines. A classical example is MPI.
 
@@ -59,8 +62,14 @@ For the relationship between latency transit time and message size see [Communic
 # Message Size
 The message size is used to refer to the size of messages in bytes used by Linktest to benchmark communication. For the relationship between latency transit time and message size see [Communication Time](#communication-time). Note that many communication APIs only support message sizes up to 2 GiB. For 32-bit MPI implementations the cumulative message size of all messages is restricted in total to less than 2 GiB.
 
-# Randomizing Testing Order
-Although by default Linktest tests the connection between a given task and all other tasks, results may depend on the order in which the testing is performed. The `--randomize` command-line option causes the testing order to be randomly mixed which means that consecutive Linktest runs with this on will likely test physical connections in a different order.
+# Memory-Buffer Allocator
+Linktest has the ability to allocate its memory buffers, which are used to store the messages for sending and the received messages, using a variety of allocators. Currently there are four options: 1) Memory-aligned malloc, 2) Pinned memory-map, 3) POSIX memory-aligned malloc and 4) CUDA malloc. Memory-aligned malloc uses the C++ function `std::aligned_alloc()`. Pinned memory-map uses the C function `mmap()`. POSIX memory-aligned malloc uses the POSIX C function `posix_memalign`. CUDA malloc uses the CUDA memory allocator to allocate memory on GPUs, this is the only option to allocate memory on GPUs.
+
+# Mode
+The `--mode` command-line option defines which communication API Linktest benchmarks. As a shorthand `-m` can be used. See [Communication API](#communication-api) for a list of supported communication APIs.
+
+# Multiple Buffers
+For the unidirectional MPI case, see [Unidirectional Testing](#unidirectional-testing) Linktest is able to use multiple buffers to send and receive messages. If there are less buffers available than messages to be sent then Linktest cycles through the buffers. The idea behind this is to avoid cache thrashing due to multiple accesses of the buffers during transfer. This can improve speed, however, often using a single buffer that can be kept in the CPU cache is more performant.
 
 # Number Of Messages
 Linktest benchmarks communications by repeating a communication many times. The amount of times it repeats the sending of messages for timing purposes is controlled via the `--num-messages` command-line argument. This defines how many times the back-and-forth sending of messages is repeated for timing purposes. The final returned times are the average time it took the message to be sent back-and-forth.
@@ -86,6 +95,9 @@ A writes average time (t2-t1)/2N to the sion file
 
 In the Matrix seen in Linktest reports this time corresponds to the entry in column A, ow B
 
+# Randomizing Testing Order
+Although by default Linktest tests the connection between a given task and all other tasks, results may depend on the order in which the testing is performed. The `--randomize` command-line option causes the testing order to be randomly mixed which means that consecutive Linktest runs with this on will likely test physical connections in a different order.
+
 # Serial Testing
 By default Linktest tests as many connections as possible in parallel, this, however, can cause tests to interfere. This is sometimes desired, for example, if real-world network performance under a sustained network load is to be tested. In other cases peak performance without the interference of other parallel tests is desired. In this case serial testing is done, in which each connection between a pair of tasks is tested individually. This effectively serializes the test and will cause it to take significantly longer. Serial testing can be turned on in Linktest by using the `--serial-testing` command-line option.
 
@@ -105,4 +117,7 @@ Transit time is the time it takes for an object to go from its origin to its des
 For the relationship between latency transit time and message size see [Communication Time](#communication-time).
 
 # Transport Layer
-In the OSI model a transport layer is conceptual division of the methods and protocols related to the transport of information, generally in terms of bytes. In Linktest it defines the API (the aforementioned methods and protocols) used to communicate data between, or within, systems. It is generally used in conjunction with which communication-API Linktest should test, which is controlled over the `--mode` option. It, however, should not be confused with the communication API used for testing. The transport layer is an abstract concept. Linktest uses the communication API for the actual establishment and testing of connections.
\ No newline at end of file
+In the OSI model a transport layer is conceptual division of the methods and protocols related to the transport of information, generally in terms of bytes. In Linktest it defines the API (the aforementioned methods and protocols) used to communicate data between, or within, systems. It is generally used in conjunction with which communication-API Linktest should test, which is controlled over the `--mode` option. It, however, should not be confused with the communication API used for testing. The transport layer is an abstract concept. Linktest uses the communication API for the actual establishment and testing of connections.
+
+# Unidirectional Testing
+Linktest using the MPI communication API can also test unidirectionally. In this case after timing begins messages are send back to back from the sending host to the receiving host. Once the receiving host received all messages it sends a receipt back to the sender, who then stops timing. The advantage of this test is that it is sensitive to the case where bandwidth is between two partners is not isotropic, i.e. the bandwidth depends on the send direction.