pymembar 0.1.2__tar.gz

pymembar-0.1.2/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Fabian Krumm
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pymembar-0.1.2/MANIFEST.in

@@ -0,0 +1,4 @@
+include include/membar.h
+include membar/__init__.pyi
+include src/membar.c
+include membarmodule.c

pymembar-0.1.2/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pymembar
+Version: 0.1.2
+Summary: Memory barrier utilities for Python - provides wmb, rmb, and fence operations
+Author-email: fwkrumm <fwkrumm@github.com>
+Maintainer-email: fwkrumm <fwkrumm@github.com>
+Project-URL: Homepage, https://github.com/fwkrumm/pymembar
+Project-URL: Repository, https://github.com/fwkrumm/pymembar
+Project-URL: Issues, https://github.com/fwkrumm/pymembar/issues
+Project-URL: Documentation, https://github.com/fwkrumm/pymembar/blob/master/README.md
+Keywords: memory-barriers,concurrency,low-level,synchronization,threading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Operating System
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# Python Memory Barrier (pymembar)
+
+Memory barrier utilities for Python - provides low-level memory ordering primitives for concurrent programming. Usually you would not need this in Python due to GIL and generally strong memory ordering on x86/x86_64. However, on weakly-ordered architectures like ARM, memory barriers can be useful for ensuring correct visibility and ordering of memory operations when for example working with shared memory, named semaphores, or lock-free data structures.
+
+I used AI (GitHub Copilot) to help generate parts of this README, documentation strings, parts of the core code, the tests, and some configuration files. Please report any inaccuracies or errors you may find.
+
+
+## Overview
+
+This package provides Python bindings for memory barrier operations, ensuring that memory operations are visible to other processes and threads in the correct order. Memory barriers do not provide synchronization themselves, but rather control the visibility and ordering of memory operations across CPU cores and processes.
+
+The package includes three core functions:
+
+- `wmb()` - Write memory barrier
+- `rmb()` - Read memory barrier
+- `fence()` - Full memory fence
+
+## Installation
+
+```bash
+pip install pymembar
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+import membar
+
+# Write memory barrier - ensures all write operations before this point
+# are visible to other processes/threads before any writes after this point
+membar.wmb()
+
+# Read memory barrier - ensures all read operations before this point
+# complete before any read operations after this point
+membar.rmb()
+
+# Full memory fence - ensures all memory operations before this point
+# are visible to other processes/threads before any operations after this point
+membar.fence()
+```
+
+### Logging Support
+
+You can enable optional logging to see which memory barrier implementation is being used at runtime. This is useful for debugging and understanding which underlying mechanism (C11 atomics, MSVC, GNU atomics, BSD, or compiler barrier) is executing on your platform.
+
+**⚠️ Performance Warning:** Enabling logging adds overhead to every memory barrier call (callback check and function call overhead). This can significantly impact performance in tight loops or performance-critical code paths. Logging should primarily be used for debugging and development, and should be disabled (`set_log_callback(None)`) in production code where performance is critical.
+
+```python
+import membar
+
+# Enable logging with a custom callback
+def my_logger(message):
+    print(f"[MEMBAR] {message}")
+
+membar.set_log_callback(my_logger)
+
+# Now all barrier calls will log their implementation
+membar.wmb()   # Logs: "wmb: using C11 atomic_thread_fence(memory_order_release)"
+membar.fence() # Logs: "fence: using C11 atomic_thread_fence(memory_order_seq_cst)"
+
+# You can also use print directly
+membar.set_log_callback(print)
+
+# Or integrate with Python's logging module
+import logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+membar.set_log_callback(logger.info)
+
+# Disable logging by passing None
+membar.set_log_callback(None)
+```
+
+## When Are Memory Barriers Needed?
+
+Memory barriers are primarily needed on weakly-ordered CPU architectures like ARM, where the processor may reorder memory operations for performance optimization. On x86/x86_64 architectures, the strong memory ordering model means that memory barriers are often not strictly necessary for most use cases, as the hardware already provides strong ordering guarantees.
+
+However, memory barriers can still be useful on x86 in specific scenarios:
+- When interfacing with memory-mapped I/O
+- In lock-free programming with specific compiler optimizations
+- When precise ordering is critical for correctness
+
+**Note:** Most Python applications will not need memory barriers due to the Global Interpreter Lock (GIL) and Python's threading model.
+
+## Requirements
+
+- Python 3.10+
+- Compatible with Windows, Linux, and macOS
+
+## Contributing
+
+I am not a C expert and would be happy to receive any constructive feedback, suggestions, or contributions to improve this library. Feel free to open issues or submit pull requests on the [GitHub repository](https://github.com/fwkrumm/pymembar).
+
+## Disclaimer
+
+Parts of the core code, the tests, this README, and documentation strings were generated with AI assistance.
+
+## Release history
+
+- 0.0.1 - Initial release
+- 0.0.2 - Added ARM build support
+- 0.0.3 - Added logging support and multiple synchronization implementations
+- 0.0.4 - Improved logging thread safety and documentation
+- 0.1.0 - Dropped EOL Python versions (3.8, 3.9); minimum is now Python 3.10
+- 0.1.1 - Removed minor-version Python classifiers; Python 3.10+ remains required.
+- 0.1.2 - Added Python 3.15 wheel and source distribution.
+
+
+## TODOs
+- Is it possible to write tests for the memory barrier core functionality?

pymembar-0.1.2/README.md

@@ -0,0 +1,112 @@
+# Python Memory Barrier (pymembar)
+
+Memory barrier utilities for Python - provides low-level memory ordering primitives for concurrent programming. Usually you would not need this in Python due to GIL and generally strong memory ordering on x86/x86_64. However, on weakly-ordered architectures like ARM, memory barriers can be useful for ensuring correct visibility and ordering of memory operations when for example working with shared memory, named semaphores, or lock-free data structures.
+
+I used AI (GitHub Copilot) to help generate parts of this README, documentation strings, parts of the core code, the tests, and some configuration files. Please report any inaccuracies or errors you may find.
+
+
+## Overview
+
+This package provides Python bindings for memory barrier operations, ensuring that memory operations are visible to other processes and threads in the correct order. Memory barriers do not provide synchronization themselves, but rather control the visibility and ordering of memory operations across CPU cores and processes.
+
+The package includes three core functions:
+
+- `wmb()` - Write memory barrier
+- `rmb()` - Read memory barrier
+- `fence()` - Full memory fence
+
+## Installation
+
+```bash
+pip install pymembar
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+import membar
+
+# Write memory barrier - ensures all write operations before this point
+# are visible to other processes/threads before any writes after this point
+membar.wmb()
+
+# Read memory barrier - ensures all read operations before this point
+# complete before any read operations after this point
+membar.rmb()
+
+# Full memory fence - ensures all memory operations before this point
+# are visible to other processes/threads before any operations after this point
+membar.fence()
+```
+
+### Logging Support
+
+You can enable optional logging to see which memory barrier implementation is being used at runtime. This is useful for debugging and understanding which underlying mechanism (C11 atomics, MSVC, GNU atomics, BSD, or compiler barrier) is executing on your platform.
+
+**⚠️ Performance Warning:** Enabling logging adds overhead to every memory barrier call (callback check and function call overhead). This can significantly impact performance in tight loops or performance-critical code paths. Logging should primarily be used for debugging and development, and should be disabled (`set_log_callback(None)`) in production code where performance is critical.
+
+```python
+import membar
+
+# Enable logging with a custom callback
+def my_logger(message):
+    print(f"[MEMBAR] {message}")
+
+membar.set_log_callback(my_logger)
+
+# Now all barrier calls will log their implementation
+membar.wmb()   # Logs: "wmb: using C11 atomic_thread_fence(memory_order_release)"
+membar.fence() # Logs: "fence: using C11 atomic_thread_fence(memory_order_seq_cst)"
+
+# You can also use print directly
+membar.set_log_callback(print)
+
+# Or integrate with Python's logging module
+import logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+membar.set_log_callback(logger.info)
+
+# Disable logging by passing None
+membar.set_log_callback(None)
+```
+
+## When Are Memory Barriers Needed?
+
+Memory barriers are primarily needed on weakly-ordered CPU architectures like ARM, where the processor may reorder memory operations for performance optimization. On x86/x86_64 architectures, the strong memory ordering model means that memory barriers are often not strictly necessary for most use cases, as the hardware already provides strong ordering guarantees.
+
+However, memory barriers can still be useful on x86 in specific scenarios:
+- When interfacing with memory-mapped I/O
+- In lock-free programming with specific compiler optimizations
+- When precise ordering is critical for correctness
+
+**Note:** Most Python applications will not need memory barriers due to the Global Interpreter Lock (GIL) and Python's threading model.
+
+## Requirements
+
+- Python 3.10+
+- Compatible with Windows, Linux, and macOS
+
+## Contributing
+
+I am not a C expert and would be happy to receive any constructive feedback, suggestions, or contributions to improve this library. Feel free to open issues or submit pull requests on the [GitHub repository](https://github.com/fwkrumm/pymembar).
+
+## Disclaimer
+
+Parts of the core code, the tests, this README, and documentation strings were generated with AI assistance.
+
+## Release history
+
+- 0.0.1 - Initial release
+- 0.0.2 - Added ARM build support
+- 0.0.3 - Added logging support and multiple synchronization implementations
+- 0.0.4 - Improved logging thread safety and documentation
+- 0.1.0 - Dropped EOL Python versions (3.8, 3.9); minimum is now Python 3.10
+- 0.1.1 - Removed minor-version Python classifiers; Python 3.10+ remains required.
+- 0.1.2 - Added Python 3.15 wheel and source distribution.
+
+
+## TODOs
+- Is it possible to write tests for the memory barrier core functionality?

pymembar-0.1.2/include/membar.h

@@ -0,0 +1,46 @@
+// membar.h
+#pragma once
+
+#ifdef _WIN32
+    #define MEMBAR_EXPORT __declspec(dllexport)
+#else
+    #define MEMBAR_EXPORT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * write memory barrier
+ * ensures that all previous memory writes are visible before any subsequent writes
+ */
+MEMBAR_EXPORT void membar_wmb(void);
+
+/**
+ * read memory barrier
+ * ensures that all previous memory reads are completed before any subsequent reads
+ */
+MEMBAR_EXPORT void membar_rmb(void);
+
+/**
+ * full fence (both read and write)
+ * provides sequential consistency across memory operations
+ */
+MEMBAR_EXPORT void membar_fence(void);
+
+/**
+ * logging callback function type
+ * @param message - the log message to output
+ */
+typedef void (*membar_log_callback)(const char* message);
+
+/**
+ * set optional logging callback
+ * @param callback - function to call for logging, or NULL to disable logging
+ */
+MEMBAR_EXPORT void membar_set_log_callback(membar_log_callback callback);
+
+#ifdef __cplusplus
+}
+#endif

pymembar-0.1.2/membar/__init__.py

@@ -0,0 +1,11 @@
+"""Memory barrier utilities: wmb, rmb, and fence operations."""
+# pylint: disable=duplicate-code
+try:
+    from ._membar import wmb, rmb, fence, set_log_callback  # Import from private C extension
+    __all__ = ['wmb', 'rmb', 'fence', 'set_log_callback']
+except ImportError as e:
+    raise ImportError(f"Could not import C extension module: {e}") from e
+
+# do NOT alter the following line in any way EXCEPT changing
+# the version number. no comments, no rename, whatsoever
+__version__ = "0.1.2"

pymembar-0.1.2/membar/__init__.pyi

@@ -0,0 +1,57 @@
+"""
+Type stubs for membar module - Memory barrier utilities for Python
+"""
+from typing import Optional, Callable
+
+def wmb() -> None:
+    """
+    Write memory barrier.
+
+    Ensures that all write operations issued before this barrier
+    are completed before any write operations issued after this barrier.
+    """
+    ...
+
+def rmb() -> None:
+    """
+    Read memory barrier.
+
+    Ensures that all read operations issued before this barrier
+    are completed before any read operations issued after this barrier.
+    """
+    ...
+
+def fence() -> None:
+    """
+    Full memory fence.
+
+    Ensures that all memory operations (both reads and writes) issued before
+    this barrier are completed before any memory operations issued after this barrier.
+    """
+    ...
+
+def set_log_callback(callback: Optional[Callable[[str], None]]) -> None:
+    """
+    Set optional logging callback.
+
+    Args:
+        callback: A callable that takes a string message, or None to disable logging.
+                  The callback will be invoked whenever a memory barrier function is called,
+                  with information about which implementation is being used.
+
+    Example:
+        >>> import membar
+        >>> membar.set_log_callback(print)
+        >>> membar.wmb()                        # will log which implementation is used
+        >>> membar.set_log_callback(None)       # disable logging
+
+    Or use a custom logger:
+        >>> import logging
+        >>> logger = logging.getLogger("membar_logger")
+        >>> membar.set_log_callback(logger.info)  # Use logger.info (can also use .debug, .warning, etc.)
+        >>> membar.rmb()                                # logs via the logger
+        >>> membar.set_log_callback(None)               # disable logging
+    """
+    ...
+
+__all__ = ['wmb', 'rmb', 'fence', 'set_log_callback']