<?php

namespace parallel;

/**
 * The Sync class provides access to low level synchronization primitives, mutex, condition variables, and allows the
 * implementation of semaphores.
 *
 * Synchronization for most applications is much better implemented using channels, however, in some cases authors of
 * low level code may find it useful to be able to access these lower level mechanisms.
 */
final class Sync
{
    /* Constructor */

    /**
     * Shall construct a new synchronization object with no value
     * Shall construct a new synchronization object containing the given scalar value
     *
     * @param string|int|float|bool $value
     *
     * @throws Sync\Error\IllegalValue if value is non-scalar.
     */
    public function __construct($value = null) {}

    /* Access */

    /**
     * Shall atomically return the synchronization objects value
     * @return string|int|float|bool
     */
    public function get() {}

    /**
     * Shall atomically set the value of the synchronization object
     * @param string|int|float|bool $value
     *
     * @throws Sync\Error\IllegalValue if value is non-scalar.
     */
    public function set($value) {}

    /* Synchronization */

    /**
     * Shall wait for notification on this synchronization object
     * @return bool
     */
    public function wait(): bool {}

    /**
     * Shall notify one (by default) or all threads waiting on the synchronization object
     * @param bool $all
     *
     * @return bool
     */
    public function notify(?bool $all = null): bool {}

    /**
     * Shall exclusively enter into the critical code
     * @param callable $block
     */
    public function __invoke(callable $block) {}
}
