Added SyncSharedMem. Updated documentation for PECL sync 1.1.0.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@341175 c90b9560-bf6c-de11-be94-00142212c4b1

reference/sync/book.xml

@@ -9,8 +9,9 @@
   &reftitle.intro;
   <para>
  The 'sync' extension introduces cross-platform synchonization objects into PHP.
- Named and unnamed Mutex, Semaphore, Event, and Reader-Writer objects provide
- OS-level synchronization on both POSIX (e.g. Linux) and Windows platforms.
+ Named and unnamed Mutex, Semaphore, Event, Reader-Writer, and named Shared Memory
+ objects provide OS-level synchronization on both POSIX (e.g. Linux) and Windows
+ platforms.
   </para>
   <para>
  Automatic cleanup of acquired synchronization objects takes place during extension
@@ -40,6 +41,7 @@
  &reference.sync.syncsemaphore;
  &reference.sync.syncevent;
  &reference.sync.syncreaderwriter;
+ &reference.sync.syncsharedmemory;
 
 </book>
 

reference/sync/setup.xml

@@ -7,7 +7,7 @@
  <section xml:id="sync.requirements">
   &reftitle.required;
   <para>
- A system with support for POSIX semaphores (sem_open()) or running Windows.
+ A system with support for POSIX shared memory (shm_open()) or running Windows.
   </para>
  </section>
 

reference/sync/syncevent/construct.xml

@@ -12,7 +12,8 @@
   <methodsynopsis>
    <modifier>public</modifier> <methodname>SyncEvent::__construct</methodname>
    <methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>manual</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>manual</parameter><initializer>false</initializer></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>prefire</parameter><initializer>false</initializer></methodparam>
   </methodsynopsis>
   <para>
  Constructs a named or unnamed event object.
@@ -51,6 +52,19 @@
      </note>
     </listitem>
    </varlistentry>
+   <varlistentry>
+    <term><parameter>prefire</parameter></term>
+    <listitem>
+     <para>
+ Specifies whether or not to prefire (signal) the event object.
+     </para>
+     <note>
+      <para>
+ Only has impact if the calling process/thread is the first to create the object.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </refsect1>
 
@@ -82,6 +96,32 @@ $event->wait();
   </example>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>1.1.0</entry>
+       <entry>
+        <para>
+         Added <parameter>prefire</parameter>.
+        </para>
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <simplelist>

reference/sync/syncevent/wait.xml

@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>SyncEvent::wait</methodname>
-   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter><initializer>-1</initializer></methodparam>
   </methodsynopsis>
   <para>
  Waits for the SyncEvent object to be fired.

reference/sync/syncmutex/lock.xml

@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>SyncMutex::lock</methodname>
-   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter><initializer>-1</initializer></methodparam>
   </methodsynopsis>
   <para>
  Obtains an exclusive lock on a SyncMutex object.

reference/sync/syncmutex/unlock.xml

@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>SyncMutex::unlock</methodname>
-   <methodparam choice="opt"><type>bool</type><parameter>all</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>all</parameter><initializer>false</initializer></methodparam>
   </methodsynopsis>
   <para>
  Decreases the internal counter of a SyncMutex object.

reference/sync/syncreaderwriter/construct.xml

@@ -12,7 +12,7 @@
   <methodsynopsis>
    <modifier>public</modifier> <methodname>SyncReaderWriter::__construct</methodname>
    <methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>autounlock</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>autounlock</parameter><initializer>true</initializer></methodparam>
   </methodsynopsis>
   <para>
  Constructs a named or unnamed reader-writer object.

reference/sync/syncreaderwriter/readlock.xml

@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>SyncReaderWriter::readlock</methodname>
-   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter><initializer>-1</initializer></methodparam>
   </methodsynopsis>
   <para>
  Obtains a read lock on a SyncReaderWriter object.

reference/sync/syncreaderwriter/writelock.xml

@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>SyncReaderWriter::writelock</methodname>
-   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter><initializer>-1</initializer></methodparam>
   </methodsynopsis>
   <para>
  Obtains an exclusive write lock on a SyncReaderWriter object.

reference/sync/syncsemaphore/construct.xml

@@ -12,8 +12,8 @@
   <methodsynopsis>
    <modifier>public</modifier> <methodname>SyncSemaphore::__construct</methodname>
    <methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam>
-   <methodparam choice="opt"><type>integer</type><parameter>initialval</parameter></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>autounlock</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>initialval</parameter><initializer>1</initializer></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>autounlock</parameter><initializer>true</initializer></methodparam>
   </methodsynopsis>
   <para>
  Constructs a named or unnamed semaphore.

reference/sync/syncsemaphore/lock.xml

@@ -11,7 +11,7 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>SyncSemaphore::lock</methodname>
-   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>wait</parameter><initializer>-1</initializer></methodparam>
   </methodsynopsis>
   <para>
  Decreases the count of a SyncSemaphore object or waits until the semaphore becomes non-zero.

reference/sync/syncsemaphore/unlock.xml

@@ -61,12 +61,6 @@ $semaphore->unlock();
 ?>
 ]]>
    </programlisting>
-   &example.outputs.similar;
-   <screen>
-<![CDATA[
-...
-]]>
-   </screen>
   </example>
  </refsect1>
 

reference/sync/syncsharedmemory.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 334161 $ -->
+
+<phpdoc:classref xml:id="class.syncsharedmemory" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The SyncSharedMemory class</title>
+ <titleabbrev>SyncSharedMemory</titleabbrev>
+
+ <partintro>
+
+<!-- {{{ SyncSharedMemory intro -->
+  <section xml:id="syncsharedmemory.intro">
+   &reftitle.intro;
+   <para>
+ A cross-platform, native, consistent implementation of named shared memory
+ objects.
+   </para>
+   <para>
+ Shared memory lets two separate processes communicate without the need for
+ complex pipes or sockets.  There are several integer-based shared memory
+ implementations for PHP.  Named shared memory is an alternative.
+   </para>
+   <para>
+ Synchronization objects (e.g. SyncMutex) are still required to protect most
+ uses of shared memory.
+   </para>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="syncsharedmemory.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>SyncSharedMemory</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>SyncSharedMemory</classname>
+     </ooclass>
+    </classsynopsisinfo>
+<!-- }}} -->
+
+    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.syncsharedmemory')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+
+ </partintro>
+
+ &reference.sync.entities.syncsharedmemory;
+
+</phpdoc:classref>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/sync/syncsharedmemory/construct.xml

@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 334180 $ -->
+
+<refentry xml:id="syncsharedmemory.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>SyncSharedMemory::__construct</refname>
+  <refpurpose>Constructs a new SyncSharedMemory object</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <methodname>SyncSharedMemory::__construct</methodname>
+   <methodparam><type>string</type><parameter>name</parameter></methodparam>
+   <methodparam><type>integer</type><parameter>size</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+ Constructs a named shared memory object.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>name</parameter></term>
+    <listitem>
+     <para>
+ The name of the shared memory object.
+     </para>
+     <note>
+      <para>
+ If the name already exists, it must be able to be opened by the current user
+ that the process is running as or an exception will be thrown with a meaningless
+ error message.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>size</parameter></term>
+    <listitem>
+     <para>
+ The size, in bytes, of shared memory to reserve.
+     </para>
+     <note>
+      <para>
+ The amount of memory cannot be resized later.  Request sufficient storage up front.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+ The new SyncSharedMemory object.  An exception is thrown if the shared memory
+ object cannot be created or opened.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>SyncSharedMemory::__construct</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// You will probably need to protect shared memory with other synchronization objects.
+// Shared memory goes away when the last reference to it disappears.
+$mem = new SyncSharedMemory("AppReportName", 1024);
+if ($mem->first())
+{
+    // Do first time initialization work here.
+}
+
+$result = $mem->write(json_encode(array("name" => "my_report.txt")));
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>SyncSharedMemory::first</methodname></member>
+   <member><methodname>SyncSharedMemory::size</methodname></member>
+   <member><methodname>SyncSharedMemory::write</methodname></member>
+   <member><methodname>SyncSharedMemory::read</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/sync/syncsharedmemory/first.xml

@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 334181 $ -->
+
+<refentry xml:id="syncsharedmemory.first" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>SyncSharedMemory::first</refname>
+  <refpurpose>Check to see if the object is the first instance system-wide of named shared memory</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>bool</type><methodname>SyncSharedMemory::first</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+ Retrieves the system-wide first instance status of a SyncSharedMemory object.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+ A boolean of TRUE if the object is the first instance system-wide, FALSE otherwise.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>SyncSharedMemory::first</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$mem = new SyncSharedMemory("AppReportName", 1024);
+if ($mem->first())
+{
+    // Do first time initialization work here.
+}
+
+var_dump($mem->first());
+
+$mem2 = new SyncSharedMemory("AppReportName", 1024);
+
+var_dump($mem2->first());
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+bool(true)
+bool(false)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>SyncSharedMemory::write</methodname></member>
+   <member><methodname>SyncSharedMemory::read</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/sync/syncsharedmemory/read.xml

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 334180 $ -->
+
+<refentry xml:id="syncsharedmemory.read" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>SyncSharedMemory::read</refname>
+  <refpurpose>Copy data from named shared memory</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <methodname>SyncSharedMemory::read</methodname>
+   <methodparam choice="opt"><type>integer</type><parameter>start</parameter><initializer>0</initializer></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>length</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+ Copies data from named shared memory.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>start</parameter></term>
+    <listitem>
+     <para>
+ The start/offset, in bytes, to begin reading.
+     </para>
+     <note>
+      <para>
+ If the value is negative, the starting position will begin at the specified
+ number of bytes from the end of the shared memory segment.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>length</parameter></term>
+    <listitem>
+     <para>
+ The number of bytes to read.
+     </para>
+     <note>
+      <para>
+ If unspecified, reading will stop at the end of the shared memory segment.
+      </para>
+      <para>
+ If the value is negative, reading will stop the specified number of bytes
+ from the end of the shared memory segment.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+ A string containing the data read from shared memory.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>SyncSharedMemory::__construct</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// You will probably need to protect shared memory with other synchronization objects.
+// Shared memory goes away when the last reference to it disappears.
+$mem = new SyncSharedMemory("AppReportName", 1024);
+if ($mem->first())
+{
+    // Do first time initialization work here.
+}
+
+$result = $mem->write("report.txt");
+
+$result = $mem->read(3, -4);
+var_dump($result);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+string(3) "ort"
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>SyncSharedMemory::__construct</methodname></member>
+   <member><methodname>SyncSharedMemory::first</methodname></member>
+   <member><methodname>SyncSharedMemory::write</methodname></member>
+   <member><methodname>SyncSharedMemory::read</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/sync/syncsharedmemory/size.xml

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 334181 $ -->
+
+<refentry xml:id="syncsharedmemory.size" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>SyncSharedMemory::size</refname>
+  <refpurpose>Returns the size of the named shared memory</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>bool</type><methodname>SyncSharedMemory::size</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+ Retrieves the shared memory size of a SyncSharedMemory object.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+ An integer containing the size of the shared memory.  This will be the same size that was passed to the constructor.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>SyncSharedMemory::size</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$mem = new SyncSharedMemory("AppReportName", 1024);
+var_dump($mem->size());
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+int(1024)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>SyncSharedMemory::__construct</methodname></member>
+   <member><methodname>SyncSharedMemory::write</methodname></member>
+   <member><methodname>SyncSharedMemory::read</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/sync/syncsharedmemory/write.xml

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 334180 $ -->
+
+<refentry xml:id="syncsharedmemory.write" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>SyncSharedMemory::write</refname>
+  <refpurpose>Copy data to named shared memory</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <methodname>SyncSharedMemory::write</methodname>
+   <methodparam choice="opt"><type>string</type><parameter>string</parameter></methodparam>
+   <methodparam choice="opt"><type>integer</type><parameter>start</parameter><initializer>0</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+ Copies data to named shared memory.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>string</parameter></term>
+    <listitem>
+     <para>
+ The data to write to shared memoy.
+     </para>
+     <note>
+      <para>
+ If the size of the data exceeds the size of the shared memory, the number of
+ bytes written returned will be less than the length of the input.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>start</parameter></term>
+    <listitem>
+     <para>
+ The start/offset, in bytes, to begin writing.
+     </para>
+     <note>
+      <para>
+ If the value is negative, the starting position will begin at the specified
+ number of bytes from the end of the shared memory segment.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+ An integer containing the number of bytes written to shared memory.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>SyncSharedMemory::write</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// You will probably need to protect shared memory with other synchronization objects.
+// Shared memory goes away when the last reference to it disappears.
+$mem = new SyncSharedMemory("AppReportName", 1024);
+if ($mem->first())
+{
+    // Do first time initialization work here.
+}
+
+$result = $mem->write("report.txt");
+var_dump($result);
+
+$result = $mem->write("report.txt", -3);
+var_dump($result);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+int(10)
+int(3)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>SyncSharedMemory::__construct</methodname></member>
+   <member><methodname>SyncSharedMemory::first</methodname></member>
+   <member><methodname>SyncSharedMemory::write</methodname></member>
+   <member><methodname>SyncSharedMemory::read</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/sync/versions.xml

@@ -17,7 +17,7 @@
  <function name='syncsemaphore::lock' from='PECL sync &gt;= 1.0.0'/>
  <function name='syncsemaphore::unlock' from='PECL sync &gt;= 1.0.0'/>
 
- <function name='syncevent' from='PECL sync &gt;= Unknown'/>
+ <function name='syncevent' from='PECL sync &gt;= 1.0.0'/>
  <function name='syncevent::__construct' from='PECL sync &gt;= 1.0.0'/>
  <function name='syncevent::wait' from='PECL sync &gt;= 1.0.0'/>
  <function name='syncevent::fire' from='PECL sync &gt;= 1.0.0'/>
@@ -29,6 +29,13 @@
  <function name='syncreaderwriter::writelock' from='PECL sync &gt;= 1.0.0'/>
  <function name='syncreaderwriter::readunlock' from='PECL sync &gt;= 1.0.0'/>
  <function name='syncreaderwriter::writeunlock' from='PECL sync &gt;= 1.0.0'/>
+
+ <function name='syncsharedmemory' from='PECL sync &gt;= 1.1.0'/>
+ <function name='syncsharedmemory::__construct' from='PECL sync &gt;= 1.1.0'/>
+ <function name='syncsharedmemory::first' from='PECL sync &gt;= 1.1.0'/>
+ <function name='syncsharedmemory::size' from='PECL sync &gt;= 1.1.0'/>
+ <function name='syncsharedmemory::write' from='PECL sync &gt;= 1.1.0'/>
+ <function name='syncsharedmemory::read' from='PECL sync &gt;= 1.1.0'/>
 </versions>
 
 <!-- Keep this comment at the end of the file