<?xml version="1.0" encoding="iso-8859-1"?>
 <reference id="ref.sem">
  <title>Semaphor und Shared Memory Funktionen</title>
  <titleabbrev>Semaphore</titleabbrev>

  <partintro>
   <para>
	  Dieses Modul bietet Untersttzung fr die Nutzung von Semaphoren
    und gemeinamen Speichersegmenten mit Hilfe der UNIX System V
    Mechanismen zur Interprozess-Kommunikation.
	 </para>
   <para>
    Mit Hilfe von Semaphoren kann der exklusive Zugriff auf Resourcen
    eines Systems sichergestellt oder die Anzahl der Prozesse begrenzt
    werden, die gleichzeitig eine bestimmte Systemresource nutzen.
   </para>
   <para>
	  Mit Hilfe gemeinsamer Speichersegmente (shared memory) knnen 
    system-globale Variablen angelegt und bereitgestellt werden. 
    Diese Speicherbereiche stehen allen Prozessen des Systems,
    insbesondere aber allen parallel laufenden PHP-Instanzen 
    zum Datenaustausch zur Verfgung. Beachten Sie bitte, das gemeinsame
    Speichersegmente keinen Schutze vor konkurierenden gleichzeitigen
    Zugriffen bieten. Benutzen Sie Semaphore fr die Koordination
    solcher Zugriffe.
	 </para>
	 <para>
    <table>
     <title>Limits of Shared Memory by the Unix OS</title>
     <tgroup cols="2">
      <tbody>
       <row>
			  <entry>SHMMAX</entry> 
			  <entry>
				 Maximalgre eines gemeinsamen Speicherbereichs, 
         blich sind 131072 Byte (128KB)
        </entry>
       </row>
       <row>
			  <entry>SHMMIN</entry>
			  <entry>
				 Minimalgre eines gemeinsamen Speicherbereichs,
				 normalerweise 1 Byte
			  </entry>
       </row>
       <row>
			  <entry>SHMMNI</entry> 
			  <entry>
				 maximale Anzahl unterschiedlicher Speichersegmente,
				 blich sind 100
			  </entry>
       </row>
       <row>
			  <entry>SHMSEG</entry>
			  <entry>
				 Anzahl der Speichersegmente, die ein einzelner Prozess
         einbinden darf, blich sind 6
			  </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    <example>
		 <title>Koordinierter Zugriff auf gemeinsamen Speicher</title>
      <programlisting role="php">
&lt;?php
// gemeinsames Speichersegment beschaffen
if(! ($mkey = shm_attach(0x2328,1024,OctDec("666")))) 
{ echo "shmem_attach fehlgeschlagen&lt;br>\n"; exit;}

// Semaphor fr Zugriffskoordination auf 
// Speichersegment beschaffen
if(! ($skey = sem_get(0x2328,1,OctDec("666")))) 
{ echo "sem_get fehlgeschlagen&lt;br>\n"; exit;}

// Zugriff anfordern
if(! sem_acquire($skey))
{ echo "sem_acquire fehlgeschlagen&lt;br>\n"; exit;}

// Wert lesen, aktualisieren und schreiben
$val = @shm_get_var($mkey,1);
if($val===false) $val=1; else $val++;
print "new value is $val&lt;br>\n";
shm_put_var($mkey,1,$val);

// Zugriff freigeben
sem_release($skey);
?&gt;
     </programlisting>
    </example>
   </para>
  </partintro>

  <refentry id="function.sem-get">
   <refnamediv>
    <refname>sem_get</refname>
    <refpurpose>Liefert ein Semaphore-Handle</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>sem_get</methodname>
      <methodparam><type>int</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>max_acquire</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>perm</parameter></methodparam>
     </methodsynopsis>
    <para>
     Diese Funktion liefert ein Handle, das fr den Zugriff auf das
     Semaphore mit der Kennung <parameter>key</parameter> benutzt 
     werden kann. 
    </para>
    <para>
		 Falls noch kein Semaphore mit dieser Kennung existiert, so wird
     es neu angelegt. Die maximale Anzahl der gleichzeitig mglichen
     Anforderungen und die Zugriffsrechte werden dabei ber die Parameter 
		 <parameter>max_aquire</parameter> und <function>sem_get</function> 
		 festgelegt.
		</para>
	  <para>
		 Wird der angeforderte Semaphore zum Zeitpunkt des Aufrufs von keiner
		 anderen Funktion genutzt, so kann ber den optionalen Parameter
     <parameter>max_aquire</parameter> die Anzahl der gelichzeitig 
		 mglichen Anforderungen neu festgelegt werden, anderenfalls bleibt
     der ursprngliche Wert erhalten.
    </para>
    <para>
     Ein zweiter Aufruf der Funktion mit demselben 
     <parameter>key</parameter> liefert ein weiteres, von dem ersten
     verschiedenes, Handle, das aber trotzdem denselben darunterliegenden
		 Semaphore anspricht.
    </para>
	  <para> 
		 Wenn kein Semaphore mit der Kennung <parameter>key</parameter> 
     angelegt werden kann oder die Rechte fr den Zugriff auf einen 
		 bestehendennicht ausreichen, so ist das Ergebnis
     dieser Funktion der Wert &false;.
		</para>
    <para> 
     Siehe auch <function>sem_acquire</function> und
     <function>sem_release</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sem-acquire">
   <refnamediv>
    <refname>sem_acquire</refname>
    <refpurpose>Zugriff auf einen Semaphore anfordern</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>sem_acquire</methodname>
      <methodparam><type>int</type><parameter>sem_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
		 <function>sem_acquire</function> blockiert die Ausfhrung (falls
     notwendig) solange, bis eine Anforderung eines Semaphores 
     durchgefhrt werden kann, d.h. solange die Anzahl der 
		 gleichzeitigen Anforderungen bereits der maximalen Anzahl 
		 entspricht.
		</para>
    <para>
		 Wird ein erfolgreich angeforderter Sempahore innerhalb eines
     Requests nicht wieder freigegeben, so erfolgt die Freigabe
		 nach Abarbeitung des Requests automatisch und es wird eine
		 Warnung ausgegeben.
		</para>
    <para>
		 Diese Funktion liefert &true; bei Erfolg und &false;, wenn eine
     Anforderung des Semaphores wegen eines Fehlers nicht mglich
     ist.
    </para>
    <para> 
     Siehe auch <function>sem_get</function> und
     <function>sem_release</function>.
    </para>
	  <warning>
	   <para>
		  Wird ein Semaphore ein zweites mal whrend desselben Request
      angefordert, ohne zwischenzeitlich freigegeben worden zu 
      sein, so kann dies dazu fhren, das die weitere Ausfhrung
      dieses Requests nicht mehr mglich ist.
     </para>
		</warning>
   </refsect1>
  </refentry>

  <refentry id="function.sem-release">
   <refnamediv>
    <refname>sem_release</refname>
    <refpurpose>Freigabe eines angeforderten Semaphores</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>sem_release</methodname>
      <methodparam><type>int</type><parameter>sem_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>sem_release</function> gibt einen zuvor angeforderten
     Semaphore wieder frei. Die Anforderung und Freigabe kann 
     innerhalb eines Prozesses mehrfach hintereinander erfolgen.
    </para>
    <para>
		 Die Funktion liefert &true;, wenn ein angeforderter Semaphore
     erfolgreich freigegeben wurde, ansonsten &false;.
    </para>
    <para> 
     Siehe auch <function>sem_get</function> und
     <function>sem_acquire</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shm-attach">
   <refnamediv>
    <refname>shm_attach</refname>
    <refpurpose>
		 Anlegen oder anbinden eines gemeinsamen Speichersegments
	  </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shm_attach</methodname>
      <methodparam><type>int</type><parameter>key</parameter></methodparam> 
      <methodparam choice="opt"><type>int</type><parameter>memsize</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>perm</parameter></methodparam>
     </methodsynopsis>
    <para>
		 <function>shm_attach</function> gibt ein Handle fr den Zugriff
     auf den gemeinsamen Speicherbereich mit der Kennung 
     <parameter>key</parameter> zurck. 
		</para>
	  <para>
		 Falls noch kein Bereich mit dieser Kennung existiert, so wird er 
		 mit einer Gre von <parameter>memsize</parameter> Byte (Vorgabe 
		 ist der Parameter <parameter>sysvshm.init_mem</parameter> aus der 
		 <link linkend="configuration.file">Konfigurationsdatei</link>
     bzw. 10000 Byte) und den Zugriffsberechtigungen gem
     <parameter>perm</parameter> (Vorgabe ist der Wert 0666, der
     Lese- und Schreibzugriffe fr alle Benutzer gestattet) an.
    </para>
    <para>
     Ein zweiter Aufruf der Funktion mit demselben 
     <parameter>key</parameter> liefert ein weiteres, von dem ersten
     verschiedenes, Handle, das aber trotzdem denselben gemeinsamen
     Speicherbereich anspricht.
    </para>
	  <para> 
		 Wenn kein Bereich mit der Kennung <parameter>key</parameter> 
     angelegt werden kann oder die Rechte fr den Zugriff auf ein 
		 bestehendes Segment nicht ausreichen, so ist das Ergebnis
     dieser Funktion der Wert &false;.
		</para>
   </refsect1>
  </refentry>

  <refentry id="function.shm-detach">
   <refnamediv>
    <refname>shm_detach</refname>
    <refpurpose>
     Beenden der Anbindung an ein gemeinsames Speichersegment
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shm_detach</methodname>
      <methodparam><type>int</type><parameter>shm_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>shm_detach</function> beendet die Anbindung eines
     gemeinsamen Speicherbreichs mit dem Handle 
		 <parameter>shm_identifier</parameter>, das zuvor ber 
		 <function>shm_attach</function> angebunden wurde. 
		 Das Segment an sich und die darin enthaltenen Daten bleiben
     erhalten und stehen nach erneuter Anbindung in diesem oder
     einem anderen Prozess wieder zur Verfgung.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shm-remove">
   <refnamediv>
    <refname>shm_remove</refname> 
    <refpurpose>Entfernt ein gemeinsames Speichersegment</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shm_remove</methodname>
      <methodparam><type>int</type><parameter>key</parameter></methodparam>
     </methodsynopsis>
    <para>
		 Diese Funktion gibt ein gemeinsames Speichersegment wieder
     frei, dabei gehen alle Daten innerhalb des Segmentes
     verloren.
    </para>
    <para>
		 Diese Funktion liefert &true;, wenn das Segment erfolgreich 
		 entfernt wurde, oder &false;, wenn kein Segment mit der Kennung 
     <parameter>key</parameter> existierte oder die Zugriffsrechte
     auf ein bestehendes Segment nicht fr ein Lschen ausreichen.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shm-put-var">
   <refnamediv>
    <refname>shm_put_var</refname> 
    <refpurpose>
		 Aktualisiert einen in einem gemeinsamen Speicherbereich
	   angelegten Wert.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shm_put_var</methodname>
      <methodparam><type>int</type><parameter>shm_identifier</parameter></methodparam>
      <methodparam><type>int</type><parameter>variable_key</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>variable</parameter></methodparam>
     </methodsynopsis>
    <para>
		 Diese Funktion weist einer Variable mit der Kennung 
		 <parameter>variable_key</parameter>
     in einem gemeinsamen Speichersegment den Wert von
		 <parameter>variable</parameter> zu, beim ersten Zugriff wird 
     <parameter>variable_key</parameter> neu angelegt.
		</para>
	  <para>
		 Diese Funktion liefert &false; zurck, wenn der verbleibende
     Speicherplatz im angegebenen Segment 
     <parameter>shm_identifier</parameter> zur Aufnahme des Wertes
     von <parameter>variable</parameter> nicht mehr ausreicht,
     ansonsten &true;.
    </para> 
   </refsect1>
  </refentry>

  <refentry id="function.shm-get-var">
   <refnamediv>
    <refname>shm_get_var</refname> 
    <refpurpose>
		 Liest einen in einem gemeinsamen Speicherbereich
	   angelegten Wert.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>mixed</type><methodname>shm_get_var</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>int</type><parameter>variable_key</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>shm_get_var</function> liefert den Wert mit der Kennung
     <parameter>variable_key</parameter> aus einem gemeinsamen 
		 Speicherbereich. Der Wert im gemeinsamen Speicher bleibt weiter 
     vorhanden. Existiert kein Wert mit der angegebenen Kennung, 
     so wird eine Warnung erzeugt und &false; zurckgegeben.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.shm-remove-var">
   <refnamediv>
    <refname>shm_remove_var</refname> 
    <refpurpose>
		 Entfernt einen in einem gemeinsamen Speicherbereich
	   angelegten Wert.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>shm_remove_var</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>int</type><parameter>variable_key</parameter></methodparam>
     </methodsynopsis>
    <para>
     Diese Funktion entfernt den Wert mit der Kennung 
     <parameter>variable_key</parameter> aus einem gemeinsamen
     Speichersegment und stellt den hiervon genutzten Speicher 
		 innerhalb des egmentes wieder zur Verfgung.
    </para>
    <para>
		 Diese Funktion liefert &true; bei Erfolg und &false;, falls kein
     Wert mit der Kennung <parameter>variable_key</parameter> im
		 Speichersegment angelegt war.
	  </para>
   </refsect1>
  </refentry>

</reference>

<!-- 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:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->