Refactor and improvements in current ParallelSTL code

* Refactored files and namespaces to clearly differentiate between the
  standard Parallel STL implementation and the SYCL policy
* Improved documentation and usage of Doxygen
* Added all variants of sort, for_each, for_each_n and transform
* Unit tests for all the algorithms
* Multiple improvements on the build systems
* Added basic benchmarking infrastructure

Author: Ruyman Reyes

.clang-format

@@ -0,0 +1,62 @@
+---
+Language:        Cpp
+# BasedOnStyle:  Google
+AccessModifierOffset: -1
+ConstructorInitializerIndentWidth: 4
+AlignEscapedNewlinesLeft: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: All
+AlwaysBreakAfterDefinitionReturnType: false
+AlwaysBreakTemplateDeclarations: true
+AlwaysBreakBeforeMultilineStrings: true
+BreakBeforeBinaryOperators: None
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BinPackParameters: true
+BinPackArguments: true
+ColumnLimit:     80
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+DerivePointerAlignment: true
+ExperimentalAutoDetectBinPacking: false
+IndentCaseLabels: true
+IndentWrappedFunctionNames: false
+IndentFunctionDeclarationAfterType: false
+MaxEmptyLinesToKeep: 1
+KeepEmptyLinesAtTheStartOfBlocks: false
+NamespaceIndentation: None
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: false
+PenaltyBreakBeforeFirstCallParameter: 1
+PenaltyBreakComment: 300
+PenaltyBreakString: 1000
+PenaltyBreakFirstLessLess: 120
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Left
+SpacesBeforeTrailingComments: 2
+Cpp11BracedListStyle: true
+Standard:        Auto
+IndentWidth:     2
+TabWidth:        8
+UseTab:          Never
+BreakBeforeBraces: Attach
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+SpacesInAngles:  false
+SpaceInEmptyParentheses: false
+SpacesInCStyleCastParentheses: false
+SpaceAfterCStyleCast: false
+SpacesInContainerLiterals: true
+SpaceBeforeAssignmentOperators: true
+ContinuationIndentWidth: 4
+CommentPragmas:  '^ IWYU pragma:'
+ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
+SpaceBeforeParens: ControlStatements
+DisableFormat:   false
+...
+

CMakeLists.txt

@@ -1,6 +1,10 @@
 cmake_minimum_required (VERSION 2.8.12.2)
 project (SyclSTL)
 
+enable_testing()
+
+option(PARALLEL_STL_BENCHMARKS "Build the internal benchmarks" OFF)
+
 if(HEADER_ONLY)
   message(WARNING "The SYCL implementation is header-only")
 else(HEADER_ONLY)
@@ -9,13 +13,13 @@ else(HEADER_ONLY)
   find_library(SYCL_LIBRARY
     NAMES SYCL SYCL_d
     HINTS ${SYCL_PATH}
-    PATH_SUFFIXES lib 
+    PATH_SUFFIXES lib
     )
 
   find_library(OPENCL_LIBRARY
-    NAMES OpenCL 
+    NAMES OpenCL
     HINTS ${OPENCL_ROOT_DIR}
-    PATH_SUFFIXES lib lib64 
+    PATH_SUFFIXES lib lib64
     )
 
   if(NOT DEFINED OPENCL_LIBRARY)
@@ -39,8 +43,8 @@ else(HEADER_ONLY)
   if (UNIX)
       # TODO(Ruyman) Figure out the linux distribution
       # Fix for device compiler not finding specific C++ headers with Ubuntu
-      set(CMAKE_INCLUDE_PATH "${CMAKE_INCLUDE_PATH}" 
-                         "/usr/include/c++/4.8.2/" 
+      set(CMAKE_INCLUDE_PATH "${CMAKE_INCLUDE_PATH}"
+                         "/usr/include/c++/4.8.2/"
                           "/usr/include/x86_64-linux-gnu/c++/4.8/")
   endif()
 
@@ -51,7 +55,7 @@ else(HEADER_ONLY)
       set(DEVICE_COMPILER_NAME "compute++")
     endif(WIN32)
   endif (NOT DEFINED DEVICE_COMPILER_NAME)
-  set(DEVICE_COMPILER "${DEVICE_COMPILER_PATH}/${DEVICE_COMPILER_NAME}" 
+  set(DEVICE_COMPILER "${DEVICE_COMPILER_PATH}/${DEVICE_COMPILER_NAME}"
     CACHE FILEPATH "device compiler")
   add_custom_target(compiler)
 
@@ -65,14 +69,47 @@ endif(HEADER_ONLY)
 include_directories("${SYCL_PATH}/include")
 include_directories("${SYCL_PATH}/include/image_library")
 
-
+#####################
+# add_sycl_target
+#
+#  Adds a file containing sycl code as a cmake target
+#  Creates the dependency to the device compiler.
+#
+#  exe_name : Final name of the executable
+#  file : Name of the source file
+#  binary_dir : Binary directory to output the .sycl files
+#
+function(add_sycl_target exe_name file binary_dir)
+  get_filename_component(filename ${file} NAME)
+  add_executable (${exe_name} ${file})
+  target_link_libraries(${exe_name} SyclSTL)
+
+  set_property(TARGET ${exe_name} PROPERTY CXX_STANDARD "11")
+  set_property(TARGET ${exe_name} PROPERTY CXX_STANDARD_REQUIRED True)
+
+
+  if (NOT HEADER_ONLY)
+    build_spir(${exe_name} ${file} ${binary_dir})
+    if (MSVC)
+     set_property(TARGET ${exe_name} PROPERTY COMPILE_FLAGS
+       "-std=c++11 /FI ${CMAKE_CURRENT_BINARY_DIR}/${filename}.sycl ${CMAKE_CXX_FLAGS}")
+     else(MSVC)
+             set_property(TARGET ${exe_name} PROPERTY COMPILE_FLAGS
+      "-std=c++11 -include ${CMAKE_CURRENT_BINARY_DIR}/${filename}.sycl ${CMAKE_CXX_FLAGS}")
+    endif(MSVC)
+  endif (NOT HEADER_ONLY)
+
+endfunction(add_sycl_target)
 
 # Build the parallel stl
 
 include_directories("include")
 
 add_subdirectory (src)
 add_subdirectory (examples)
-add_subdirectory (tests)
 
+add_subdirectory (tests)
 
+if (PARALLEL_STL_BENCHMARKS)
+  add_subdirectory (benchmarks)
+endif()

README.md

@@ -7,9 +7,9 @@ using the Khronos SYCL standard.
 What is Parallel STL
 -----------------------
 
-Parallel STL is an implementation of the Technical Specification for C++ 
-Extensions for Parallelism, current document number 
-[N4409](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4409.pdf).
+Parallel STL is an implementation of the Technical Specification for C++
+Extensions for Parallelism, current document number
+[N4507](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4507.pdf).
 This technical specification describes _a set of requirements for
 implementations of an interface that computer programs written in
 C++ programming language may use to invoke algorithms with parallel
@@ -19,27 +19,25 @@ offers the opportunity to users to specify _execution policies_ to
 traditional STL algorithms, which will enable the execution of
 those algorithms in parallel.
 The various policies can specify different kinds of parallel execution.
-For example, 
-
-```c++
-std::vector<int> v = ...
-// Traditional sequential sort
-std::sort(vec.begin(), vec.end());
-// Explicit sequential sort
-std::sort(seq, vec.begin(), vec.end());
-// Explicit parallel sort
-std::sort(par, vec.begin(), vec.end());
-```
+For example,
+
+    std::vector<int> v = ...
+    // Traditional sequential sort
+    std::sort(vec.begin(), vec.end());
+    // Explicit sequential sort
+    std::sort(seq, vec.begin(), vec.end());
+    // Explicit parallel sort
+    std::sort(par, vec.begin(), vec.end());
+
 
 What is SYCL
 ----------------------
 
-[SYCL](https://www.khronos.org/opencl/sycl) is a royalty-free, 
+[SYCL](https://www.khronos.org/opencl/sycl) is a royalty-free,
 cross-platform C++ abstraction layer that builds on top of OpenCL.
 SYCL enables single-source development of OpenCL applications in C++ whilst
 enabling traditional host compilers to produce standard C++ code.
 
-
 The SyclSTL
 ---------------------
 
@@ -50,11 +48,11 @@ Currently, the following STL algorithms are implemented:
 * sort : Bitonic sort for ranges which size is power of two, sequential sort
 otherwise.
 * transform : Parallel iteration (one thread per element) on the device.
-* for_each  : Parallel iteration (one thread per element) on the device.
+* for\_each  : Parallel iteration (one thread per element) on the device.
 
 Some optimizations are implemented, for example, the ability of passing
 iterators to buffers rather than STL containers to reduce the amount of
-information copied in and out, and the ability of specifying a queue 
+information copied in and out, and the ability of specifying a queue
 to the SYCL policy so that queue is used for the various kernels (potentially
 enabling asynchronous execution of the calls).
 
@@ -64,14 +62,38 @@ Building the project
 The project uses CMake in order to produce build files.
 Simply create a build directory and run CMake as follows:
 
-```
-$ mkdir build
-$ cd build
-$ cmake ../ -DSYCL_PATH=/path/to/sycl \
-            -DOPENCL_ROOT_DIR=/path/to/opencl/dir
-$ make
-```
+    $ mkdir build
+    $ cd build
+    $ cmake ../ -DSYCL_PATH=/path/to/sycl \
+                -DOPENCL_ROOT_DIR=/path/to/opencl/dir
+    $ make
+
 Usual CMake options are available (e.g. building debug or release).
 
-If Google Mock is found in external/gmock then the unit tests are build.
+If Google Mock is found in external/gmock, a set of unit tests is built.
+Unit tests can be run by running Ctest in the binary directory.
+
+Building the documentation
+----------------------------
+
+Source code is documented using Doxygen.
+To build the documentation as an HTML file, navigate to the doc
+directory and run doxygen from there.
+
+    $ cd doc
+    $ doxygen
+
+This will generate the html pages inside the doc\_output directory.
+
+Limitations
+------------
+
+The Lambda functions that you can pass to the algorithms have the same
+restrictions as any SYCL kernel.
+
+While using lambda functions, the compiler needs to find a name for that lambda
+function. To provide a lambda name, the user do the following:
 
+    cl::sycl::queue q;S
+    sycl::sycl_execution_policy<class SortAlgorithm3> snp(q);
+    sort(snp, v.begin(), v.end(), [=](int a, int b) { return a >= b; });

TODO.md

@@ -0,0 +1,8 @@
+Parallel STL TODO List
+==============================
+
+Next tasks to be done
+-----------------------
+
+Include the specialization of commonly templated std functions, such as
+std::is_equals and similar ones.

benchmarks/CMakeLists.txt

@@ -0,0 +1,10 @@
+file(GLOB EXAMPLE_FILES ./*.cpp)
+
+foreach(file ${EXAMPLE_FILES})
+  get_filename_component(filename ${file} NAME)
+  set(exe_name "${filename}.exe")
+
+  message(STATUS "File ${file} Filename ${filename}  Exename ${exe_name}")
+  add_sycl_target(${exe_name} ${file} ${CMAKE_CURRENT_BINARY_DIR})
+
+endforeach()

benchmarks/basic.cpp

@@ -0,0 +1,60 @@
+/* Copyright (c) 2015 The Khronos Group Inc.
+
+   Permission is hereby granted, free of charge, to any person obtaining a
+   copy of this software and/or associated documentation files (the
+   "Materials"), to deal in the Materials without restriction, including
+   without limitation the rights to use, copy, modify, merge, publish,
+   distribute, sublicense, and/or sell copies of the Materials, and to
+   permit persons to whom the Materials are furnished to do so, subject to
+   the following conditions:
+
+   The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Materials.
+
+   MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
+   KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
+   SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
+    https://www.khronos.org/registry/
+
+  THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
+
+*/
+
+#include <algorithm>
+#include <vector>
+#include <string>
+#include <iostream>
+
+#include <experimental/algorithm>
+#include <sycl/execution_policy>
+
+#include "benchmark.h"
+
+using namespace sycl::helpers;
+
+benchmark<>::time_units_t benchmark_sort(const unsigned numReps,
+                                         const unsigned num_elems) {
+  std::vector<int> v1;
+
+  for (int i = num_elems; i > 0; i--) {
+    v1.push_back(i);
+  }
+
+  cl::sycl::queue q;
+  sycl::sycl_execution_policy<class SortAlgorithm1> snp(q);
+
+  auto time = benchmark<>::duration(
+      numReps,
+      std::experimental::parallel::sort<decltype(snp), decltype(begin(v1))>,
+      snp, begin(v1), end(v1));
+
+  return time;
+}
+
+BENCHMARK_MAIN("BENCH_SORT", benchmark_sort, 2u, 33554432u, 10);