Single Threaded + Emscripten Support (#301)

* Rough draft of Emscripten and single threaded support

* Use different classes for CSVRow deques

* Disable threads automatically for Emscripten

* Update basic_csv_parser.hpp

Fix Emscripten failure

* Update CMakeLists.txt

* Update csv_row.hpp

Reduce duplication

* More clean-up

* Auto-disable threads if not detected

* Fixed version detection macro

* Final polish

 * Run emscripten tests
 * Very minor BasicCSVParser constructor fix
 * Documentation updates

* Update README.md

* Fix CI failures

* Disable file-reading tests for Emscripten suite

* Minor issues

* Fix test failures

* Added more file guards

* Added more guards

* Update test_edge_cases_large_rows.cpp

* Disable Emscripten tests for now

Author: vincentlaucsb

.github/workflows/cmake-multi-platform.yml

@@ -95,5 +95,76 @@ jobs:
       # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
       run: ctest --build-config ${{ matrix.build_type }}
 
+  single-threaded:
+    name: Single-threaded build (CSV_ENABLE_THREADS=OFF)
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository and submodules
+      uses: actions/checkout@v5
+      with:
+        submodules: recursive
+
+    - name: Configure CMake (single-threaded)
+      run: >
+        cmake -B ${{ github.workspace }}/build-single-thread
+        -DCSV_ENABLE_THREADS=OFF
+        -DCSV_CXX_STANDARD=20
+        -DCMAKE_BUILD_TYPE=Release
+        -S ${{ github.workspace }}
+
+    - name: Build (single-threaded)
+      run: cmake --build ${{ github.workspace }}/build-single-thread --config Release
+
+    - name: Test (single-threaded)
+      working-directory: ${{ github.workspace }}/build-single-thread
+      run: ctest --build-config Release --output-on-failure
+
+  single-threaded-emscripten:
+    name: Single-threaded Emscripten build (CSV_ENABLE_THREADS=OFF)
+    runs-on: ubuntu-latest
+    env:
+      # TODO: Set to '1' to re-enable wasm runtime tests once a lightweight
+      # Emscripten smoke subset is in place and stable in CI.
+      CSV_EMSCRIPTEN_RUN_TESTS: '0'
+
+    steps:
+    - name: Checkout repository and submodules
+      uses: actions/checkout@v5
+      with:
+        submodules: recursive
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.x'
+
+    - name: Set up Emscripten
+      uses: mymindstorm/setup-emsdk@667eb33f24e84e7f362c16d8d7fff0629a73e15e # v14
+      with:
+        version: latest
+
+    - name: Configure CMake (single-threaded emscripten)
+      run: >
+        emcmake cmake -B ${{ github.workspace }}/build-single-thread-emscripten
+        -DCSV_ENABLE_THREADS=OFF
+        -DCSV_CXX_STANDARD=20
+        -DCSV_BUILD_SINGLE_INCLUDE_TEST=ON
+        -DCMAKE_CROSSCOMPILING_EMULATOR=node
+        -DCMAKE_BUILD_TYPE=Release
+        -S ${{ github.workspace }}
+
+    - name: Build (single-threaded emscripten)
+      run: cmake --build ${{ github.workspace }}/build-single-thread-emscripten --config Release
+
+    - name: Test (single-threaded emscripten)
+      if: env.CSV_EMSCRIPTEN_RUN_TESTS == '1'
+      working-directory: ${{ github.workspace }}/build-single-thread-emscripten
+      run: ctest --build-config Release --output-on-failure
+
+    - name: Skip tests (single-threaded emscripten)
+      if: env.CSV_EMSCRIPTEN_RUN_TESTS != '1'
+      run: echo "Skipping Emscripten ctest (build-only coverage). Set CSV_EMSCRIPTEN_RUN_TESTS=1 to re-enable."
+
 
 

AGENTS.md

@@ -73,5 +73,6 @@ ThreadSafeDeque<CSVRow>
 3. **Don't use uniform values:** Each column needs distinct values to detect corruption.
 4. **Don't ignore async:** Worker thread means exceptions must use `exception_ptr`.
 5. **Don't change one constructor:** Likely affects both mmap and stream paths.
+6. **Don't delete or simplify comments** unless they are trivially obvious (e.g. `// increment i`) or factually incorrect. Comments in this codebase frequently encode concurrency invariants, non-obvious design decisions, and hard-won bug context that cannot be recovered from the code alone.
 
 See `tests/AGENTS.md` for test strategy, checklist, and conventions.

CLAUDE.md

@@ -32,6 +32,7 @@
 - Use distinct column values to detect field corruption
 - Exceptions from worker thread need `exception_ptr`
 - Changes to one constructor likely affect both paths
+- **Do not delete or simplify comments** unless trivially obvious or factually wrong — comments encode concurrency invariants and bug history
 
 ## Tests
 See `tests/AGENTS.md` for full test strategy, checklist, and conventions.

CMakeLists.txt

@@ -10,18 +10,35 @@ endif(CSV_CXX_STANDARD)
 option(BUILD_PYTHON "Build Python Binding" OFF)
 option(CSV_BUILD_SINGLE_INCLUDE_TEST "Build single-header smoke test (requires Python)" OFF)
 option(ENABLE_CODE_COVERAGE "Enable code coverage instrumentation" OFF)
+option(CSV_ENABLE_THREADS "Enable multi-threaded CSV parsing" ON)
 
-message("Building CSV library using C++${CMAKE_CXX_STANDARD}")
+if(EMSCRIPTEN AND CSV_ENABLE_THREADS)
+  message(STATUS "Emscripten target detected: forcing CSV_ENABLE_THREADS=OFF")
+  set(CSV_ENABLE_THREADS OFF CACHE BOOL "Enable multi-threaded CSV parsing" FORCE)
+endif()
+
+if(EMSCRIPTEN)
+  message(STATUS "Emscripten target detected: enabling C++ exceptions (-fexceptions)")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fexceptions")
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fexceptions")
+endif()
 
-# Defines CSV_HAS_CXX17 in compatibility.hpp
-if (CMAKE_VERSION VERSION_LESS "3.12.0")
-	add_definitions(-DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD})
+if(CSV_ENABLE_THREADS)
+  message(STATUS "CSV_ENABLE_THREADS enabled: multi-threaded mode")
 else()
-	add_compile_definitions(CMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD})
+  message(STATUS "CSV_ENABLE_THREADS disabled: single-threaded mode")
 endif()
 
-set(THREADS_PREFER_PTHREAD_FLAG TRUE)
-find_package(Threads QUIET REQUIRED)
+message("Building CSV library using C++${CMAKE_CXX_STANDARD}")
+
+if(CSV_ENABLE_THREADS)
+  set(THREADS_PREFER_PTHREAD_FLAG TRUE)
+  find_package(Threads QUIET)
+  if(NOT Threads_FOUND)
+    message(STATUS "Threads package not found: forcing CSV_ENABLE_THREADS=OFF")
+    set(CSV_ENABLE_THREADS OFF CACHE BOOL "Enable multi-threaded CSV parsing" FORCE)
+  endif()
+endif()
 
 if(MSVC)
 	# Make Visual Studio report accurate C++ version

README.md

@@ -15,6 +15,8 @@
   - [Sponsors](#sponsors)
   - [Integration](#integration)
     - [C++ Version](#c-version)
+    - [Threading Modes](#threading-modes)
+    - [Emscripten / WebAssembly](#emscripten--webassembly)
     - [Single Header](#single-header)
     - [CMake Instructions](#cmake-instructions)
       - [Avoid cloning with FetchContent](#avoid-cloning-with-fetchcontent)
@@ -124,6 +126,30 @@ While C++17 is recommended, C++11 is the minimum version required. This library
 
 This library requires C++ exceptions to be enabled (for example, do not compile with `-fno-exceptions`).
 
+### Threading Modes
+By default, `csv-parser` uses a background thread to parse file-based input. If CMake cannot find a thread library, threading is disabled automatically.
+
+You can also disable it explicitly:
+
+**CMake**
+```cmake
+set(CSV_ENABLE_THREADS OFF)
+add_subdirectory(csv-parser)
+```
+
+**Non-CMake (define the macro before any csv-parser header)**
+```cpp
+#define CSV_ENABLE_THREADS 0
+#include "csv.hpp"
+```
+
+Single-threaded mode is useful for embedded targets, environments where `std::thread` is unavailable, and WebAssembly builds without pthreads. The public API is unchanged; parsing simply runs synchronously on the caller's thread.
+
+### Emscripten / WebAssembly
+On Emscripten, `CSV_ENABLE_THREADS` is forced off and memory-mapped parsing is replaced by the stream-based parser. The filename constructor (`CSVReader("file.csv")`) still works—it opens an `std::ifstream` internally instead of using mmap.
+
+Emscripten builds must keep C++ exceptions enabled. In practice, compile/link with exception support (for example, `-fexceptions`) and do not disable exception catching.
+
 ### Single Header
 **[📥 Download csv.hpp](https://vincentlaucsb.github.io/csv-parser/csv.hpp)** — Available on GitHub Pages
 
@@ -141,6 +167,10 @@ and add the following to your CMakeLists.txt:
 ```
 # Optional: Defaults to C++ 17
 # set(CSV_CXX_STANDARD 11)
+
+# Optional: disable background parsing threads
+# set(CSV_ENABLE_THREADS OFF)
+
 add_subdirectory(csv-parser)
 
 # ...

include/csv.hpp

@@ -1,5 +1,5 @@
 /*
-CSV for C++, version 2.5.2
+CSV for C++, version 3.0.0
 https://github.com/vincentlaucsb/csv-parser
 
 MIT License

include/internal/CMakeLists.txt

@@ -23,9 +23,18 @@ target_sources(csv
 		data_type.hpp
 		raw_csv_data.hpp
 		raw_csv_data.cpp
+		row_deque.hpp
+		single_thread_deque.hpp
 		thread_safe_deque.hpp
 		)
 
 set_target_properties(csv PROPERTIES LINKER_LANGUAGE CXX)
-target_link_libraries(csv PRIVATE Threads::Threads)
+
+if(CSV_ENABLE_THREADS)
+	target_compile_definitions(csv PUBLIC CSV_ENABLE_THREADS=1)
+	target_link_libraries(csv PRIVATE Threads::Threads)
+else()
+	target_compile_definitions(csv PUBLIC CSV_ENABLE_THREADS=0)
+endif()
+
 target_include_directories(csv INTERFACE ../)

include/internal/basic_csv_parser.cpp

@@ -6,11 +6,19 @@ namespace csv {
     namespace internals {
         CSV_INLINE size_t get_file_size(csv::string_view filename) {
             std::ifstream infile(std::string(filename), std::ios::binary);
+            if (!infile.is_open()) {
+                throw std::runtime_error("Cannot open file " + std::string(filename));
+            }
+
             const auto start = infile.tellg();
             infile.seekg(0, std::ios::end);
             const auto end = infile.tellg();
 
-            return end - start;
+            if (start < 0 || end < 0) {
+                throw std::runtime_error("Cannot determine file size for " + std::string(filename));
+            }
+
+            return static_cast<size_t>(end - start);
         }
 
         CSV_INLINE std::string get_csv_head(csv::string_view filename) {
@@ -20,6 +28,19 @@ namespace csv {
         CSV_INLINE std::string get_csv_head(csv::string_view filename, size_t file_size) {
             const size_t bytes = 500000;
 
+#if defined(__EMSCRIPTEN__)
+            std::ifstream infile(std::string(filename), std::ios::binary);
+            if (!infile.is_open()) {
+                throw std::runtime_error("Cannot open file " + std::string(filename));
+            }
+
+            const size_t length = std::min((size_t)file_size, bytes);
+            std::string head(length, '\0');
+            infile.read(&head[0], (std::streamsize)length);
+            head.resize((size_t)infile.gcount());
+            return head;
+#else
+
             std::error_code error;
             size_t length = std::min((size_t)file_size, bytes);
             auto mmap = mio::make_mmap_source(std::string(filename), 0, length, error);
@@ -29,6 +50,7 @@ namespace csv {
             }
 
             return std::string(mmap.begin(), mmap.end());
+#endif
         }
 
 #ifdef _MSC_VER
@@ -234,6 +256,7 @@ namespace csv {
 #ifdef _MSC_VER
 #pragma region Specializations
 #endif
+#if !defined(__EMSCRIPTEN__)
         CSV_INLINE void MmapParser::next(size_t bytes = ITERATION_CHUNK_SIZE) {
             // CRITICAL SECTION: Chunk Transition Logic
             // This function reads 10MB chunks and must correctly handle fields that span
@@ -289,6 +312,7 @@ namespace csv {
 
             this->mmap_pos -= (length - remainder);
         }
+#endif
 #ifdef _MSC_VER
 #pragma endregion
 #endif

include/internal/basic_csv_parser.hpp

@@ -9,15 +9,16 @@
 #include <memory>
 #include <unordered_map>
 #include <unordered_set>
-#include <thread>
 #include <vector>
 
+#if !defined(__EMSCRIPTEN__)
 #include "../external/mio.hpp"
+#endif
 #include "col_names.hpp"
 #include "common.hpp"
 #include "csv_format.hpp"
 #include "csv_row.hpp"
-#include "thread_safe_deque.hpp"
+#include "row_deque.hpp"
 
 namespace csv {
     namespace internals {
@@ -240,15 +241,15 @@ namespace csv {
                     const auto end = _source.tellg();
                     _source.seekg(0, std::ios::beg);
 
-                    source_size = end - start;
+                    source_size = static_cast<size_t>(end - start);
                 }
 
                 // Read data into buffer
                 size_t length = std::min(source_size - stream_pos, bytes);
                 std::unique_ptr<char[]> buff(new char[length]);
                 _source.seekg(stream_pos, std::ios::beg);
                 _source.read(buff.get(), length);
-                stream_pos = _source.tellg();
+                stream_pos = static_cast<size_t>(_source.tellg());
                 ((std::string*)(this->data_ptr->_data.get()))->assign(buff.get(), length);
 
                 // Create string_view
@@ -272,6 +273,7 @@ namespace csv {
             size_t stream_pos = 0;
         };
 
+#if !defined(__EMSCRIPTEN__)
         /** Parser for memory-mapped files
          *
          *  @par Implementation
@@ -299,5 +301,6 @@ namespace csv {
             std::string _filename;
             size_t mmap_pos = 0;
         };
+#endif
     }
 }

include/internal/common.hpp

@@ -28,11 +28,22 @@
 #pragma once
 #include <type_traits>
 
+#if defined(__EMSCRIPTEN__)
+#undef CSV_ENABLE_THREADS
+#define CSV_ENABLE_THREADS 0
+#elif !defined(CSV_ENABLE_THREADS)
+#define CSV_ENABLE_THREADS 1
+#endif
+
 // Minimal portability macros (Hedley subset) with CSV_ prefix.
 #if defined(__clang__) || defined(__GNUC__)
     #define CSV_CONST __attribute__((__const__))
     #define CSV_PURE __attribute__((__pure__))
-    #define CSV_PRIVATE __attribute__((__visibility__("hidden")))
+    #if defined(_WIN32)
+        #define CSV_PRIVATE
+    #else
+        #define CSV_PRIVATE __attribute__((__visibility__("hidden")))
+    #endif
     #define CSV_NON_NULL(...) __attribute__((__nonnull__(__VA_ARGS__)))
 #elif defined(_MSC_VER)
     #define CSV_CONST
@@ -73,15 +84,15 @@
 #  define CSV_CPLUSPLUS __cplusplus
 #endif
 
-#if (defined(CMAKE_CXX_STANDARD) && CMAKE_CXX_STANDARD == 20) || CSV_CPLUSPLUS >= 202002L
+#if CSV_CPLUSPLUS >= 202002L
 #define CSV_HAS_CXX20
 #endif
 
-#if (defined(CMAKE_CXX_STANDARD) && CMAKE_CXX_STANDARD == 17) || CSV_CPLUSPLUS >= 201703L
+#if CSV_CPLUSPLUS >= 201703L
 #define CSV_HAS_CXX17
 #endif
 
-#if (defined(CMAKE_CXX_STANDARD) && CMAKE_CXX_STANDARD >= 14) || CSV_CPLUSPLUS >= 201402L
+#if CSV_CPLUSPLUS >= 201402L
 #define CSV_HAS_CXX14
 #endif