Rindow Math Buffer Ffi Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require rindow/rindow-math-buffer-ffi
   

   Ensure your project uses PHP 8.1+ and runs on Linux/macOS/Windows.

2. First Use Case: Buffer Creation

   use Rindow\Math\Buffer\FFI\Buffer;
   
   // Initialize FFI buffer (adjust path to your math library)
   $ffi = FFI::cdef("
       typedef double double_t;
       double_t *malloc(size_t size);
       void free(double_t *ptr);
   ", 'path/to/your/math_library.so');
   
   $buffer = new Buffer($ffi, 10); // Buffer of 10 doubles
   $buffer->fill(0.0); // Fill with zeros
   

3. Key Entry Points

   • Buffer::create(): Initialize a new buffer.
   • Buffer::fill(): Set all values to a scalar.
   • Buffer::get()/Buffer::set(): Access individual elements.
   • Buffer::toArray()/Buffer::fromArray(): Convert between PHP arrays and FFI buffers.

Implementation Patterns

Core Workflows

1. Data Exchange with C Libraries

   // Pass buffer to C function (e.g., BLAS/LAPACK)
   $ffi->my_c_function($buffer->getPointer(), $buffer->getSize());
   

2. Batch Operations

   // Fill with sequential values
   for ($i = 0; $i < $buffer->getSize(); $i++) {
       $buffer->set($i, $i * 1.5);
   }
   

3. Memory Management

   // Explicit cleanup (if not using RAII)
   $buffer->free();
   

Integration Tips

• Leverage with Rindow Math Libraries Combine with rindow/math for matrix operations:

  use Rindow\Math\Matrix\Matrix;
  
  $matrix = Matrix::create(3, 3);
  $buffer = $matrix->toBuffer(); // Convert to FFI buffer
  

• Performance Optimization

  • Pre-allocate buffers for repeated operations.
  • Use Buffer::copy() to avoid reallocations.

• Type Safety Ensure FFI cdef matches the target library’s signatures (e.g., double_t for BLAS).

Gotchas and Tips

Pitfalls

1. FFI Initialization Errors

   • Symptom: FFI::cdef() fails silently or throws cryptic errors.
   • Fix: Verify the library path is correct and the FFI signature matches the C header.

     // Debug: Check if the library loads
     $ffi = FFI::load('math_library.so');
     

2. Memory Leaks

   • Symptom: Buffer values persist after expected cleanup.
   • Fix: Always call $buffer->free() or use a finally block:

     try {
         $buffer = new Buffer($ffi, 100);
         // ... operations ...
     } finally {
         $buffer->free();
     }
     

3. Cross-Platform Quirks

   • Windows: Use .dll paths (e.g., 'C:\path\to\lib.dll').
   • macOS/Linux: Ensure library permissions allow FFI access (chmod +r library.so).

4. PHPUnit Hang (macOS)

   • Workaround: Use a custom GitHub Actions setup or Docker for testing.

Debugging Tips

• Inspect Buffer Contents

  print_r($buffer->toArray());
  

• FFI Verbosity Enable FFI debugging in php.ini:

  ffi.debug = 1
  

Extension Points

1. Custom Buffer Types Extend Buffer to support complex numbers or mixed types:

   class ComplexBuffer extends Buffer {
       public function setComplex(int $index, float $real, float $imag): void {
           $this->set($index * 2, $real);
           $this->set($index * 2 + 1, $imag);
       }
   }
   

2. Integration with Laravel

   • Service Provider: Register FFI buffers as a singleton:

     $this->app->singleton('math.buffer', function ($app) {
         $ffi = FFI::load('vendor/math_library.so');
         return new Buffer($ffi, 1024);
     });
     

   • Facade: Create a MathBuffer facade for cleaner syntax:

     use Illuminate\Support\Facades\Facade;
     
     class MathBuffer extends Facade {
         protected static function getFacadeAccessor() { return 'math.buffer'; }
     }
     

3. Async Operations Use Swoole or ReactPHP to offload heavy computations to worker processes:

   $buffer = new Buffer($ffi, 1000);
   $worker = new \Swoole\Process(function () use ($buffer) {
       // Heavy math ops here
   });