1#############################################################################
2##
3##  This file is part of GAP, a system for computational discrete algebra.
4##  This file's authors include Steve Linton.
5##
6##  Copyright of GAP belongs to its developers, whose names are too numerous
7##  to list here. Please refer to the COPYRIGHT file for details.
8##
9##  SPDX-License-Identifier: GPL-2.0-or-later
10##
11##  This file contains the definition of operations and functions for
12##  weak pointers.
13##
14##  WP objects behave in most respects like mutable plain lists, except that
15##  they do not keep their subobjects alive, so that one sees things like.
16##
17##  gap> w := WeakPointerObj([[1,2]]);;
18##  gap> IsBound(w[1]);
19##  true
20##  gap> GASMAN("collect");
21##  gap> w;
22##  WeakPointerObj([ [ ] ]);
23##
24##  for this reason the common idiom
25##
26##  if IsBound(w[i]) then
27##     DoSomethigWith(w[i]);
28##  fi;
29##
30##  is not really safe.
31##
32##  A solution is provided by the kernel function ElmWPObj (weakptr.c), which
33##  returns fail if the entry is (1) unbound or (2) bound to the value fail.
34##  Since fail will never be collected as garbage, a subsequent call to IsBound
35##  can safely be used to distinguish these two cases, as in:
36##
37##  x := ElmWPObj(w,i);
38##  if x <> fail or IsBound(w[i]) then
39##     DoSomethingWith(x);
40##  else
41##     DoSomethingElse();
42##  fi;
43##
44
45
46
47#############################################################################
48##
49##
50#C  IsWeakPointerObject( <obj> ) . . .  . . . . . . . category of  WP objects
51##
52##  All WP objects have to be mutable (a stronger term like volatile would
53##  be appropriate),
54##  but this cannot be expressed via an explicit implication;
55##  note that `Immutable' is handled by the kernel.
56##
57
58DeclareCategoryKernel( "IsWeakPointerObject",
59    IsList and IsSmallList,
60    IsWPObj );
61