Quelle regions.xml Sprache: XML

<Chapter Label="How HPC-GAP organizes shared memory: Regions">
  <Heading>How HPC-GAP organizes shared memory: Regions</Heading>

HPC-GAP allows multiple threads to access data shared between them; to avoid common concurrency errors, such as race
conditions, it partitions GAP objects into regions. Access to regions is regulated so that no two threads can modify
objects in the same region at the same time and so that objects that are being read by one thread cannot concurrently be
modified by another.

  <Section Label="Thread-local regions">
    <Heading>Thread-local regions</Heading>

Each thread has an associated thread-local region. When a thread implicitly or explicitly creates a new object, that
object initially belongs to the thread's thread-local region.
<P/>
Only the thread can read or modify objects in its thread-local region. For other threads to access an object, that
object has to be migrated into a different region first.

  </Section>
  <Section Label="Shared regions">
    <Heading>Shared regions</Heading>

Shared regions are explicitly created through the <Ref Func="ShareObj"/> and <Ref Func="ShareSingleObj"/> primitives
(see below). Multiple threads can access them concurrently, but accessing them requires that a thread uses an
<C>atomic</C> statement to acquire a read or write lock beforehand.
<P/>
See the section on <C>atomic</C> statements (<Ref Sect="The atomic statement."/>) for details.

  </Section>
  <Section Label="Ordering of shared regions">
    <Heading>Ordering of shared regions</Heading>

Shared regions are by default ordered; each shared region has an associated numeric precedence level. Regions can
generally only be locked in order of descending precedence. The purpose of this mechanism is to avoid accidental
deadlocks.
<P/>
The ordering requirement can be overridden in two ways: regions with a negative precedence are excluded from it. This
exception should be used with care, as it can lead to deadlocks.
<P/>
Alternatively, two or more regions can be locked simultaneously via the <C>atomic</C> statement. In this case, the
ordering of these regions relative to each other can be arbitrary.

  </Section>
  <Section Label="The public region">
    <Heading>The public region</Heading>

A special public region contains objects that only permit atomic operations. These include, in particular, all immutable
objects (immutable in the sense that their in-memory representation cannot change).
<P/>
All threads can access objects in the public region at all times without needing to acquire a read- or write-lock
beforehand.

  </Section>
  <Section Label="The read-only region">
    <Heading>The read-only region</Heading>

The read-only region is another special region that contains objects that are only meant to be read; attempting to
modify an object in that region will result in a runtime error. To obtain a modifiable copy of such an object, the <Ref
Func="CopyRegion"/> primitive can be used.

  </Section>
  <Section Label="Migrating objects between regions">
    <Heading>Migrating objects between regions</Heading>

Objects can be migrated between regions using a number of functions. In order to migrate an object, the current thread
must have exclusive access to that object; the object must be in its thread-local region or it must be in a shared
region for which the current thread holds a write lock.
<P/>
The <Ref Func="ShareObj"/> and <Ref Func="ShareSingleObj"/> functions create a new shared region and migrate their
respective argument to that region; <C>ShareObj</C> will also migrate all subobjects that are within the same region,
while <C>ShareSingleObj</C> will leave the subobjects unaffected.
<P/>
The <Ref Func="MigrateObj"/> and <Ref Func="MigrateSingleObj"/> functions migrate objects to an existing region. The
first argument of either function is the object to be migrated; the second is either a region (as returned by the <Ref
Func="RegionOf"/> function) or an object whose containing region the first argument is to be migrated to.
<P/>
The current thread needs exclusive access to the target region (denoted by the second argument) for the operation to
succeed. If successful, the first argument will be in the same region as the second argument afterwards. In the case of
<Ref Func="MigrateObj"/>, all subobjects within the same region as the first argument will also be migrated to the target
region.
<P/>
Finally, <Ref Func="AdoptObj"/> and <Ref Func="AdoptSingleObj"/> are special cases of <Ref Func="MigrateObj"/> and
<Ref Func="MigrateSingleObj"/>, where the target region is the thread-local region of the current thread.
<P/>
To migrate objects to the read-only region, one can use <Ref Func="MakeReadOnlyObj"/> and <Ref Func="MakeReadOnlySingleObj"/>.
The first migrates its argument and all its subjobjects that are within the same region to the read-only region; the
second migrates only the argument itself, but not its subobjects.
<P/>
It is generally not possible to migrate objects explicitly to the public region; only objects with purely atomic
operations can be made public and that is done automatically when they are created.
<P/>
The exception are immutable objects. When <Ref BookName="ref" Func="MakeImmutable"/> is used, its argument is automatically moved to the
public region.

<Example><![CDATA[
gap> RegionOf(MakeImmutable([1,2,3]));
<public region>
]]></Example>

  </Section>
  <Section Label="Region names">
    <Heading>Region names</Heading>

Regions can be given names, either explicitly via <Ref Func="SetRegionName"/> or when they are created via <Ref
Func="ShareObj"/> and <Ref Func="ShareSingleObj"/>. Thread-local regions, the public, and the readonly region are given
names by default.
<P/>
Multiple regions can have the same name.

  </Section>
  <Section Label="Controlling access to regions">
    <Heading>Controlling access to regions</Heading>

If either GAP code or a kernel primitive attempts to access an object that it is not allowed to access according to
these semantics, either a "write guard error" (for a failed write access) or a "read guard error"
(for a failed read access) will be raised. The global variable <C>LastInaccessible</C> will contain the object that
caused such an error.
<P/>
One exception is that threads can modify objects in regions that they have only read access (but not write access) to
using write-once functions - see section <Ref Sect="Write-once functionality"/>.
<P/>
To inspect objects whose contents lie in other regions (and therefore cannot be displayed by
<Ref BookName="ref" Func="PrintObj"/> or <Ref BookName="ref" Func="ViewObj"/>,
the functions <Ref Func="ViewShared"/> and <Ref Func="UNSAFE_VIEW"/> can be used.

  </Section>
  <Section Label="Functions relating to regions">
    <Heading>Functions relating to regions</Heading>

<ManSection>
    <Func Name="NewRegion"
      Arg='[name, ] prec'/>

<Description>
The function <Ref Func="NewRegion"/> creates a new shared region.
If the optional argument <A>name</A> is provided, then the
name of the new region will be set to <A>name</A>.

<Example><![CDATA[
gap> NewRegion("example region");
<region: example region>
]]></Example>

<Ref Func="NewRegion"/> will create a region with a high precedence level. It is intended to be called by user code. The exact
precedence level can be adjusted with <A>prec</A>, which must be an integer in the range <C>[-1000..1000]</C>;
<A>prec</A> will be added to the normal precedence level.
</Description>
</ManSection>

<ManSection>
    <Func Name="NewLibraryRegion"
      Arg='[name, ] prec'/>

<Description>
<Ref Func="NewLibraryRegion"/> functions like <Ref Func="NewRegion"/>,
except that the precedence of the region it creates is below
that of <Ref Func="NewRegion"/>. It is intended to be used by user libraries and GAP packages.
</Description>
</ManSection>

<ManSection>
    <Func Name="NewSystemRegion"
      Arg='[name, ] prec'/>

<Description>
<Ref Func="NewSystemRegion"/> functions like <Ref Func="NewRegion"/>,
except that the precedence of the region it creates is below
that of <Ref Func="NewLibraryRegion"/>. It is intended to be used by the standard GAP library.
</Description>
</ManSection>

<ManSection>
    <Func Name="NewKernelRegion"
      Arg='[name, ] prec'/>

<Description>
<Ref Func="NewKernelRegion"/> functions like <Ref Func="NewRegion"/>, except that the precedence of the region it creates is below
that of <Ref Func="NewSystemRegion"/>. It is intended to be used by the GAP kernel, and GAP library code that interacts closely
with the kernel.
</Description>
</ManSection>

<ManSection>
    <Func Name="NewInternalRegion"
      Arg='[name]'/>

<Description>
<Ref Func="NewInternalRegion"/> functions like <Ref Func="NewRegion"/>, except that the precedence of the region it creates is the
lowest available. It is intended to be used for regions that are self-contained; i.e. no function that uses such a
region may lock another region while accessing it. The precedence level of an internal region cannot be adjusted.
</Description>
</ManSection>

<ManSection>
    <Func Name="NewSpecialRegion"
      Arg='[name]'/>

<Description>
<Ref Func="NewLibraryRegion"/> functions like <Ref Func="NewRegion"/>, except that the precedence of the region it creates is
negative. It is thus exempt from normal ordering and deadlock checks.
</Description>
</ManSection>

<ManSection>
    <Func Name="RegionOf"
      Arg='obj'/>

<Description>
<Example><![CDATA[
gap> RegionOf(1/2);
<public region>
gap> RegionOf([1,2,3]);
<region: thread region #0>
gap> RegionOf(ShareObj([1,2,3]));
<region 0x45deaa0>
gap> RegionOf(ShareObj([1,2,3]));
<region 0x45deaa0>
gap> RegionOf(ShareObj([1,2,3], "test region"));
<region: test region>
]]></Example>

Note that the unique number that each region is identified with is system-specific and can change each time the code is
being run.

Region objects returned by <C>RegionOf</C> can be compared:

<Example><![CDATA[
gap> RegionOf([1,2,3]) = RegionOf([4,5,6]);
true
]]></Example>

The result in this example is true because both lists are in the same thread-local region.
</Description>
</ManSection>

<ManSection>
    <Func Name="RegionPrecedence"
      Arg='obj'/>

<Description>
<Ref Func="RegionPrecedence"/> will return the precedence of the region of <A>obj</A>.

<Example><![CDATA[
gap> RegionPrecedence(NewRegion("Test"));
30000
gap> RegionPrecedence(NewRegion("Test2", 1));
30001
gap> RegionPrecedence(NewLibraryRegion("LibTest", -1));
19999
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
The <Ref Func="ShareObj"/> function creates a new shared region and migrates the object and all its subobjects to that region.
If the optional argument <A>name</A> is provided, then the name of the new region is set to <A>name</A>.
<P/>
<Ref Func="ShareObj"/> will create a region with a high precedence level. It is intended to be called by user code. The actual
precedence level can be adjusted by the optional <A>prec</A> argument in the same way as for <Ref Func="NewRegion"/>.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareLibraryObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
<Ref Func="ShareLibraryObj"/> functions like <Ref Func="ShareObj"/>, except that the precedence of the region it creates is below that
of <Ref Func="ShareObj"/>. It is intended to be used by user libraries and GAP packages.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSystemObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
<Ref Func="ShareSystemObj"/> functions like <Ref Func="ShareObj"/>, except that the precedence of the region it creates is below that
of <Ref Func="ShareLibraryObj"/>. It is intended to be used by the standard GAP library.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareKernelObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
<Ref Func="ShareKernelObj"/> functions like <Ref Func="ShareObj"/>, except that the precedence of the region it creates is below that
of <Ref Func="ShareSystemObj"/>. It is intended to be used by the GAP kernel, and GAP library code that interacts closely with
the kernel.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareInternalObj"
      Arg='obj[, name]'/>

<Description>
<Ref Func="ShareInternalObj"/> functions like <Ref Func="ShareObj"/>, except that the precedence of the region it creates is the
lowest available. It is intended to be used for regions that are self-contained; i.e. no function that uses such a
region may lock another region while accessing it.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSpecialObj"
      Arg='obj[, name]'/>

<Description>
<Ref Func="ShareSpecialObj"/> functions like <Ref Func="ShareObj"/>, except that the precedence of the region it creates is negative.
It is thus exempt from normal ordering and deadlock checks.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSingleObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
The <Ref Func="ShareSingleObj"/> function creates a new shared region and migrates the object, but not its subobjects, to that
region. If the optional argument <A>name</A> is provided, then the name of the new region is set to <A>name</A>.

<Example><![CDATA[
gap> m := [ [1, 2], [3, 4] ];;
gap> ShareSingleObj(m);;
gap> atomic readonly m do
>      Display([ IsShared(m), IsShared(m[1]), IsShared(m[2]) ]);
>    od;
[ true, false, false ]
]]></Example>

<Ref Func="ShareSingleObj"/> will create a region with a high precedence level. It is intended to be called by user code. The
actual precedence level can be adjusted by the optional <A>prec</A> argument in the same way as for <Ref Func="NewRegion"/>.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSingleLibraryObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
<Ref Func="ShareSingleLibraryObj"/> functions like <Ref Func="ShareSingleObj"/>, except that the precedence of the region it creates
is below that of <Ref Func="ShareSingleObj"/>. It is intended to be used by user libraries and GAP packages.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSingleSystemObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
<Ref Func="ShareSingleSystemObj"/> functions like <Ref Func="ShareSingleObj"/>, except that the precedence of the region it creates is
below that of <Ref Func="ShareSingleLibraryObj"/>. It is intended to be used by the standard GAP library.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSingleKernelObj"
      Arg='obj [, [ name, ] prec]'/>

<Description>
<Ref Func="ShareSingleKernelObj"/> functions like <Ref Func="ShareSingleObj"/>, except that the precedence of the region it creates is
below that of <Ref Func="ShareSingleSystemObj"/>. It is intended to be used by the GAP kernel, and GAP library code that
interacts closely with the kernel.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSingleInternalObj"
      Arg='obj[, name]'/>

<Description>
<Ref Func="ShareSingleInternalObj"/> functions like <Ref Func="ShareSingleObj"/>, except that the precedence of the region it creates
is the lowest available. It is intended to be used for regions that are self-contained; i.e. no function that uses such
a region may lock another region while accessing it.
</Description>
</ManSection>

<ManSection>
    <Func Name="ShareSingleSpecialObj"
      Arg='obj[, name]'/>

<Description>
<Ref Func="ShareSingleLibraryObj"/> functions like <Ref Func="ShareSingleObj"/>, except that the precedence of the region it creates
is negative. It is thus exempt from normal ordering and deadlock checks.
</Description>
</ManSection>

<ManSection>
    <Func Name="MigrateObj"
      Arg='obj, target'/>

<Description>
The <Ref Func="MigrateObj"/> function migrates <A>obj</A> (and all subobjects contained within the same region) to the region
denoted by the <A>target</A> argument. Here, <A>target</A> can either be a region object returned by <Ref Func="RegionOf"/> or
a normal gap object. If <A>target</A> is a normal gap object, <A>obj</A> will be migrated to the region containing
<C>target</C>.
<P/>
For the operation to succeed, the current thread must have exclusive access to the target region and the object being
migrated.
</Description>
</ManSection>

<ManSection>
    <Func Name="MigrateSingleObj"
      Arg='obj, target'/>

<Description>
The <Ref Func="MigrateSingleObj"/> function works like <Ref Func="MigrateObj"/>, except that it does not migrate the subobjects
of <C>obj</C>.
</Description>
</ManSection>

<ManSection>
    <Func Name="LockAndMigrateObj"
      Arg='obj, target'/>

<Description>
The <Ref Func="LockAndMigrateObj"/> function works like <Ref Func="MigrateObj"/>, except that it will automatically try to
acquire a lock for the region containing <A>target</A> if it does not have one already.
</Description>
</ManSection>

<ManSection>
    <Func Name="IncorporateObj"
      Arg='target, index, value'/>

<Description>
The <Ref Func="IncorporateObj"/> function allows convenient migration to a shared list or record. If <A>target</A> is a list,
then <Ref Func="IncorporateObj"/> is equivalent to:

<Example><![CDATA[
IncorporateObj := function(target, index, value)
  atomic value do
    target[index] := MigrateObj(value, target)
  od;
end;
]]></Example>

If <A>target</A> is a record, then it is equivalent to:

<Example><![CDATA[
IncorporateObj := function(target, index, value)
  atomic value do
    target.(index) := MigrateObj(value, target)
  od;
end;
]]></Example>

The intended purpose is the population of a shared list or record with values after its creation.

Example:

<Example><![CDATA[
gap> list := ShareObj([]);
gap> atomic list do
>      IncorporateObj(list, 1, [1,2,3]);
>      IncorporateObj(list, 2, [4,5,6]);
>      IncorporateObj(list, 3, [7,8,9]);
>    od;
gap> ViewShared(list);
[ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]
]]></Example>

Using plain assignment would leave the newly created lists in the thread-local region.
</Description>
</ManSection>

<ManSection>
    <Func Name="AtomicIncorporateObj"
      Arg='target, index, value'/>

<Description>
<Ref Func="AtomicIncorporateObj"/> extends <Ref Func="IncorporateObj"/> by also
locking the target. I.e., for a list, it is equivalent to:

<Example><![CDATA[
AtomicIncorporateObj := function(target, index, value)
  atomic target, value do
    target[index] := MigrateObj(value, target)
  od;
end;
]]></Example>

If <C>target</C> is a record, then it is equivalent to:

<Example><![CDATA[
AtomicIncorporateObj := function(target, index, value)
  atomic value do
    target.(index) := MigrateObj(value, target)
  od;
end;
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="AdoptObj"
      Arg='obj'/>

<Description>
The <Ref Func="AdoptObj"/> function migrates <A>obj</A> (and all its subobjects contained within the same region) to the
thread's current region. It requires exclusive access to <A>obj</A>.

<Example><![CDATA[
gap> l := ShareObj([1,2,3]);;
gap> IsThreadLocal(l);
false
gap> atomic l do AdoptObj(l); od;
gap> IsThreadLocal(l);
true
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="AdoptSingleObj"
      Arg='obj'/>

<Description>
The <Ref Func="AdoptSingleObj"/> function works like <Ref Func="AdoptObj"/>, except that it does not migrate the subobjects of
<A>obj</A>.
</Description>
</ManSection>

<ManSection>
    <Func Name="LockAndAdoptObj"
      Arg='obj'/>

<Description>
The <Ref Func="LockAndAdoptObj"/> function works like <Ref Func="AdoptObj"/>, except that it will attempt acquire an exclusive
lock for the region containing <A>obj</A> if it does not have one already.
</Description>
</ManSection>

<ManSection>
    <Func Name="CopyRegion"
      Arg='obj'/>

<Description>
The <Ref Func="CopyRegion"/> function performs a structural copy of <A>obj</A>. The resulting objects will be located in the
current thread's thread-local region. The function returns the copy as its result.

<Example><![CDATA[
gap> l := MakeReadOnlyObj([1,2,3]);
[ 1, 2, 3 ]
gap> l2 := CopyRegion(l);
[ 1, 2, 3 ]
gap> RegionOf(l) = RegionOf(l2);
false
gap> IsIdenticalObj(l, l2);
false
gap> l = l2;
true
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="IsPublic"
      Arg='obj'/>

<Description>
The <Ref Func="IsPublic"/> function returns true if its argument is an object in the public region, false otherwise.

<Example><![CDATA[
gap> IsPublic(1/2);
true
gap> IsPublic([1,2,3]);
false
gap> IsPublic(ShareObj([1,2,3]));
false
gap> IsPublic(MakeImmutable([1,2,3]));
true
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="IsThreadLocal"
      Arg='obj'/>

<Description>
The <Ref Func="IsThreadLocal"/> function returns true if its argument is an object in the current thread's thread-local
region, false otherwise.

<Example><![CDATA[
gap> IsThreadLocal([1,2,3]);
true
gap> IsThreadLocal(ShareObj([1,2,3]));
false
gap> IsThreadLocal(1/2);
false
gap> RegionOf(1/2);
<public region>
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="IsShared"
      Arg='obj'/>

<Description>
The <Ref Func="IsShared"/> function returns true if its argument is an object in a shared region. Note that if the current
thread does not hold a lock on that shared region, another thread can migrate <A>obj</A> to a different region before
the result is being evaluated; this can lead to race conditions. The function is intended primarily for debugging, not
to build actual program logic around.
</Description>
</ManSection>

<ManSection>
    <Func Name="HaveReadAccess"
      Arg='obj'/>

<Description>
The <Ref Func="HaveReadAccess"/> function returns true if the current thread has read access to <A>obj</A>.

<Example><![CDATA[
gap> HaveReadAccess([1,2,3]);
true
gap> l := ShareObj([1,2,3]);;
gap> HaveReadAccess(l);
false
gap> atomic readonly l do t := HaveReadAccess(l); od;; t;
true
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="HaveWriteAccess"
      Arg='obj'/>

<Description>
The <Ref Func="HaveWriteAccess"/> function returns true if the current thread has write access to <A>obj</A>.

<Example><![CDATA[
gap> HaveWriteAccess([1,2,3]);
true
gap> l := ShareObj([1,2,3]);;
gap> HaveWriteAccess(l);
false
gap> atomic readwrite l do t := HaveWriteAccess(l); od;; t;
true
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="MakeReadOnlyObj"
      Arg='obj'/>

<Description>
The <Ref Func="MakeReadOnlyObj"/> function migrates <A>obj</A> and all its subobjects that are within the same region as
<A>obj</A> to the read-only region. It returns <A>obj</A>.
</Description>
</ManSection>

<ManSection>
    <Func Name="MakeReadOnlySingleObj"
      Arg='obj'/>

<Description>
The <Ref Func="MakeReadOnlySingleObj"/> function migrates <A>obj</A>, but not any of its subobjects, to the read-only region. It
returns <A>obj</A>.
</Description>
</ManSection>

<ManSection>
    <Func Name="IsReadOnlyObj"
      Arg='obj'/>

<Description>
The <Ref Func="IsReadOnlyObj"/> function returns <K>true</K> if <A>obj</A> is in the read-only region, <K>false</K> otherwise.

<Example><![CDATA[
gap> IsReadOnlyObj([1,2,3]);
false
gap> IsReadOnlyObj(MakeImmutable([1,2,3]));
false
gap> IsReadOnlyObj(MakeReadOnlyObj([1,2,3]));
true
]]></Example>
</Description>
</ManSection>

<ManSection>
    <Func Name="SetRegionName"
      Arg='obj, name'/>

<Description>
The <Ref Func="SetRegionName"/> function sets the name of the region of <A>obj</A> to <A>name</A>.
</Description>
</ManSection>

<ManSection>
    <Func Name="ClearRegionName"
      Arg='obj'/>

<Description>
The <Ref Func="ClearRegionName"/> function clears the name of the region of <A>obj</A> to <A>name</A>.
</Description>
</ManSection>

<ManSection>
    <Func Name="RegionName"
      Arg='obj'/>

<Description>
The <Ref Func="RegionName"/> function returns the name of the region of <A>obj</A>. If that region does not have a name,
<K>fail</K> will be returned.
</Description>
</ManSection>

<ManSection>
    <Func Name="ViewShared"
      Arg='obj'/>

<Description>
The <Ref Func="ViewShared"/> function allows the inspection of objects in shared regions. It will try to lock the region and
then call <C>ViewObj(obj)</C>. If it cannot acquire a lock for the region, it will simply display the normal description
of the object.
</Description>
</ManSection>

<ManSection>
    <Func Name="UNSAFE_VIEW"
      Arg='obj'/>

<Description>
The <Ref Func="UNSAFE_VIEW"/> function allows the inspection of any object in the system, regardless of whether the current
thread has access to the region containing it. It should be used with care: If the object inspected is being modified by
another thread concurrently, the resulting behavior is undefined.
<P/>
Moreover, the function works by temporarily disabling read and write guards for regions, so other threads may corrupt
memory rather than producing errors.
<P/>
It is generally safe to use if all threads but the current one are paused.
</Description>
</ManSection>

    <Subsection Label="The atomic statement.">
      <Heading>The <C>atomic</C> statement.</Heading>

<Index Key="atomic" Subkey="no value"><K>atomic</K></Index>
The <C>atomic</C> statement ensures exclusive or read-only access to one or more shared regions for statements within
its scope. It has the following syntax:

<Example><![CDATA[
atomic ([readwrite|readonly] expr (, expr)* )* do
  statements
od;
]]></Example>

Each expression is evaluated and the region containing the resulting object is locked with either a read-write or
read-only lock, depending on the keyword preceding the expression. If neither the <C>readwrite</C> nor the
<C>readonly</C> keyword was provided, read-write locks are used by default.

Examples:

<Example><![CDATA[
gap> l := ShareObj([1,2,3]);;
gap> atomic readwrite l do l[3] := 9; od;
gap> atomic l do l[2] := 4; od;
gap> atomic readonly l do Display(l); od;
[ 1, 4, 9 ]
]]></Example>

<Example><![CDATA[
gap> l := ShareObj([1,2,3,4,5]);;
gap> l2 := ShareObj([6,7,8]);;
gap> atomic readwrite l, readonly l2 do
>      for i in [1..3] do l[i] := l2[i]; od;
>      l3 := AdoptObj(l);
>    od;
gap> l3;
[ 6, 7, 8, 4, 5 ]
]]></Example>

Atomic statements must observe region ordering. That means that the highest precedence level of a region locked by an
atomic statement must be less than the lowest precedene level of a region that is locked by the same thread at the time
the atomic statement is executed.
    </Subsection>
  </Section>
  <Section Label="Atomic functions">
    <Heading>Atomic functions</Heading>

Instead of atomic regions, entire functions can be declared to be atomic. This has the same effect as though the
function's body were enclosed in an atomic statement. Function arguments can be declared either <C>readwrite</C> or
<C>readonly</C>; they will be locked in the same way as for a lock statement. If a function argument is preceded by
neither <C>readwrite</C> nor <C>readonly</C>, the corresponding object will not be locked.

Example:

<Example><![CDATA[
gap> AddAtomic := atomic function(readwrite list, readonly item)
>      Add(list, item);
>    end;
]]></Example>

  </Section>
  <Section Label="Write-once functionality">
    <Heading>Write-once functionality</Heading>

There is an exception to the rule that objects can only be modified if a thread has write access to a region. A limited
sets of objects can be modified using the "bind once" family of functions. These allow the modifications of
objects to which a thread has read access in a limited fashion.
<P/>
For reasons of implementation symmetry, these functions can also be used on the atomic versions of these objects.
<P/>
Implementation note: The functionality is not currently available for component objects.

<ManSection>
    <Func Name="BindOnce"
      Arg='obj, index, value'/>

<Description>
<Ref Func="BindOnce"/> modifies <A>obj</A>, which can be a positional object, atomic positional object, component object, or
atomic component object. It inspects <C>obj![index]</C> for the positional versions or <C>obj!.(index)</C> for the
component versions. If the respective element is not yet bound, <A>value</A> is assigned to that element. Otherwise, no
modification happens. The test and modification occur as one atomic step. The function returns the value of the element;
i.e. the old value if the element was bound and <A>value</A> if it was unbound.
<P/>
The intent of this function is to allow concurrent initialization of objects, where multiple threads may attempt to set
a value concurrently. Only one will succeed; all threads can then use the return value of <Ref Func="BindOnce"/> as the
definitive value of the element. It also allows for the lazy initialization of objects in the read-only region.
<P/>
The current thread needs to have at least read access to <A>obj</A>, but does not require write access.
</Description>
</ManSection>

<ManSection>
    <Func Name="TestBindOnce"
      Arg='obj, index, value'/>

<Description>
<Ref Func="TestBindOnce"/> works like <Ref Func="BindOnce"/>, except that it returns <K>true</K> if the value could be bound and
<K>false</K> otherwise.
</Description>
</ManSection>

<ManSection>
    <Func Name="BindOnceExpr"
      Arg='obj, index, expr'/>

<Description>
<Ref Func="BindOnceExpr"/> works like <Ref Func="BindOnce"/>, except that it evaluates the parameterless function <A>expr</A> to
determine the value. It will only evaluate <A>expr</A> if the element is not bound.
<P/>
For positional objects, the implementation works as follows:

<Example><![CDATA[
BindOnceExprPosObj := function(obj, index, expr)
  if not IsBound(obj![index]) then
    return BindOnce(obj, index, expr());
  else
    return obj![index]);
  fi;
end;
]]></Example>

The implementation for component objects works analogously.
<P/>
The intent is to avoid unnecessary computations if the value is already bound. Note that this cannot be avoided
entirely, because <C>obj![index]</C> or <C>obj!.(index)</C> can be bound while <A>expr</A> is evaluated, but it can
minimize such occurrences.
</Description>
</ManSection>

<ManSection>
    <Func Name="TestBindOnceExpr"
      Arg='obj, index, expr'/>

<Description>
<Ref Func="TestBindOnceExpr"/> works like <Ref Func="BindOnceExpr"/>, except that it returns <K>true</K> if the value could be bound
and <K>false</K> otherwise.
</Description>
</ManSection>

<ManSection>
    <Func Name="StrictBindOnce"
      Arg='obj, index, expr'/>

<Description>
<Ref Func="StrictBindOnce"/> works like <Ref Func="BindOnce"/>, except that it raises an error if the element is already bound. This
is intended for cases where a read-only object is initialized, but where another thread trying to initialize it
concurrently would be an error.
</Description>
</ManSection>
  </Section>
</Chapter>

quality91%

¤ Dauer der Verarbeitung: 0.51 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.