Acme-Parataxis

 view release on metacpan or  search on metacpan

META.json  view on Meta::CPAN

      "file" : [],
      "namespace" : [],
      "package" : []
   },
   "prereqs" : {
      "build" : {
         "requires" : {
            "Test2::V1" : "0"
         }
      },
      "configure" : {
         "requires" : {
            "Affix" : "v1.0.7",
            "Affix::Build" : "0",
            "CPAN::Meta" : "2.150012",
            "Exporter" : "5.57",
            "ExtUtils::Helpers" : "0.028",
            "ExtUtils::Install" : "0",
            "ExtUtils::InstallPaths" : "0.002",
            "File::Basename" : "0",
            "File::Find" : "0",

META.yml  view on Meta::CPAN

---
abstract: 'A dangerous hybrid of cooperative fibers and preemptive native threads'
author:
  - 'Sanko Robinson <sanko@cpan.org>'
build_requires:
  Test2::V1: '0'
configure_requires:
  Affix: v1.0.7
  Affix::Build: '0'
  CPAN::Meta: '2.150012'
  Exporter: '5.57'
  ExtUtils::Helpers: '0.028'
  ExtUtils::Install: '0'
  ExtUtils::InstallPaths: '0.002'
  File::Basename: '0'
  File::Find: '0'
  File::Path: '0'

README.md  view on Meta::CPAN

Sets the maximum number of worker threads the pool is allowed to spawn. By default, this is set to the number of
logical CPU cores detected on your system (up to a hard limit of 64).

```
# Limit the pool to 4 threads
set_max_threads(4);
```

## `max_threads( )`

Returns the currently configured maximum thread pool size.

# BLOCKING & I/O FUNCTIONS

These functions **suspend** the current fiber and offload the actual blocking work to the native thread pool.

## `await_sleep( $ms )`

Suspends the fiber for `$ms` milliseconds. While the background thread sleeps, other fibers can continue to execute.

## `await_read( $fh, $timeout = 5000 )`

README.md  view on Meta::CPAN

# BEST PRACTICES & GOTCHAS

- **Avoid blocking syscalls:** Never call blocking `sleep( )` or `sysread( )` on the main interpretation thread.
Always use the `await_*` equivalents to offload work to the pool.
- **Thread Safety:** While Perl code remains single-threaded, background tasks run on separate OS threads. Shared
C-level data (if accessed via FFI) must be mutex-protected.
- **Stack Limits:** Each fiber is allocated a 512KB stack by default. This is more than sufficient for most
Perl code and allows for high concurrency with a small memory footprint. Extremely deep recursion or massive regex
backtracking might still hit limits.
- **Efficiency:** The native thread pool is initialized dynamically upon the first asynchronous request. It
starts with a small "seed" pool and grows on demand up to the configured limit. Worker threads use condition
variables to sleep efficiently when idle, ensuring near-zero CPU usage when no background tasks are pending.
- **Reference Cycles:** Be careful when passing fiber objects into their own closures, as this can create
memory leaks.

# GORY TECHNICAL DETAILS

## Architectural Inspiration

The concurrency model in Parataxis is heavily inspired by the **Wren** programming language, specifically its treatment
of fibers as the primary unit of execution and its deterministic cooperative scheduling.

cpanfile  view on Meta::CPAN

requires 'Affix', 'v1.0.7';
requires 'File::Basename';
requires 'File::Spec';
on configure => sub {
    requires 'Affix', 'v1.0.7';
    requires 'Affix::Build';
    requires 'CPAN::Meta',        '2.150012';
    requires 'Exporter',          '5.57';
    requires 'ExtUtils::Helpers', '0.028';
    requires 'ExtUtils::Install';
    requires 'ExtUtils::InstallPaths', '0.002';
    requires 'File::Basename';
    requires 'File::Find';
    requires 'File::Path';

lib/Acme/Parataxis.pod  view on Meta::CPAN

=head2 C<set_max_threads( $count )>

Sets the maximum number of worker threads the pool is allowed to spawn. By default, this is set to the number of
logical CPU cores detected on your system (up to a hard limit of 64).

    # Limit the pool to 4 threads
    set_max_threads(4);

=head2 C<max_threads( )>

Returns the currently configured maximum thread pool size.

=head1 BLOCKING & I/O FUNCTIONS

These functions B<suspend> the current fiber and offload the actual blocking work to the native thread pool.

=head2 C<await_sleep( $ms )>

Suspends the fiber for C<$ms> milliseconds. While the background thread sleeps, other fibers can continue to execute.

=head2 C<await_read( $fh, $timeout = 5000 )>

lib/Acme/Parataxis.pod  view on Meta::CPAN

Always use the C<await_*> equivalents to offload work to the pool.

=item * B<Thread Safety:> While Perl code remains single-threaded, background tasks run on separate OS threads. Shared
C-level data (if accessed via FFI) must be mutex-protected.

=item * B<Stack Limits:> Each fiber is allocated a 512KB stack by default. This is more than sufficient for most
Perl code and allows for high concurrency with a small memory footprint. Extremely deep recursion or massive regex
backtracking might still hit limits.

=item * B<Efficiency:> The native thread pool is initialized dynamically upon the first asynchronous request. It
starts with a small "seed" pool and grows on demand up to the configured limit. Worker threads use condition
variables to sleep efficiently when idle, ensuring near-zero CPU usage when no background tasks are pending.

=item * B<Reference Cycles:> Be careful when passing fiber objects into their own closures, as this can create
memory leaks.

=back

=head1 GORY TECHNICAL DETAILS

=head2 Architectural Inspiration