adacl-pointer-shared_with_delete.ads

1------------------------------------------------------------------------------
2--: Copyright © 2003 … 2023 Martin Krischik «krischik@users.sourceforge.net»
3------------------------------------------------------------------------------
4--: This library is free software; you can redistribute it and/or modify it
5--: under the terms of the GNU Library General Public License as published by
6--: the Free Software Foundation; either version 2 of the License, or (at your
7--: option) any later version.
8--:
9--: This library is distributed in the hope that it will be useful, but
10--: WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11--: or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12--: License for more details.
13--:
14--: You should have received a copy of the GNU Library General Public License
15--: along with this library; if not, write to the Free Software Foundation,
16--: Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17----------------------------------------------------------------------------
18
19pragma License (Modified_Gpl);
20pragma Ada_2022;
21
22with Ada.Strings.Text_Buffers;
23with AdaCL.Base;
24
25---
26-- @summary
27-- AdaCL: Shared smart pointer.
28--
29-- @description
30-- Smart pointer with which can share an access. The referenced element is deleted when the last reference is removed.
31--
32--: Element_Type the element which are handled by the pointer
33--: Pointer Access to the element type
34--: Deleter function to delete an element instance
35generic
36 type Element_Type (<>) is limited private;
37 type Pointer is access Element_Type;
38 with procedure Deleter (X : in out Pointer) is <> with
39 Post => X = null;
40package AdaCL.Pointer.Shared_With_Delete is
41 ---
42 -- A Pointer to an unique element.
43 --
44 type Object is new AdaCL.Base.Object with private;
45
46 ---
47 -- Creates a new unique smart pointer from normal pointer.
48 --
49 --: @param Referent Pointer to reference counted object
50 --: @return New smart pointer
51 function Create (Referent : in Pointer := null) return Object;
52
53 ---
54 -- Checks if a pointers is set
55 --
56 --: @param This Object itself.
57 --: @return true when pointer is not null
58 function Exist (This : in Object) return Boolean with
59 Pure_Function, Inline;
60
61 ---
62 -- gets pointer to element to perform operations on. Do not save the pointer.
63 --
64 --: @param This Object itself.
65 --: @return pointer to element
66 function Get (This : in Object) return not null Pointer with
67 Inline, Pre => (This.Exist), Post => (Get'Result /= null);
68
69 ---
70 -- Replaces the managed object.
71 --
72 --: @param This Object itself.
73 --: @param Referent new pointer to manage
74 procedure Reset (This : in out Object; Referent : in Pointer := null);
75
76 ---
77 -- swaps the managed objects
78 --
79 --: @param This Object itself.
80 --: @param Other Object to swap Referents with
81 procedure Swap (This : in out Object; Other : in out Object);
82
83 ---
84 -- returns the number of shared_ptr objects referring to the same managed object.
85 --
86 --: @return use count
87 function Use_Count (This : in Object) return Natural with
88 Inline, Post => (This.Exist xor Use_Count'Result = 0);
89
90 ---
91 -- checks whether the managed object is managed only by the current shared_ptr instance
92 --
93 --: @return true when use counter is one.
94 function Unique (This : in Object) return Boolean with
95 Inline, Post => (This.Use_Count /= 1 xor Unique'Result);
96
97private
98
99 ---
100 -- Self referencing type consisting of three components: This component holds the actual data. Details in the body.
101 --
102 type Instance_Type;
103
104 ---
105 -- Self referencing type consisting of three components: type of the self reference
106 --
107 type Instance_Access is access Instance_Type;
108
109 ---
110 -- A Pointer to an unique element.
111 --
112 --: @field Self internal data kept as access to enable adjust to have Adjust to both instances.
113 type Object is new AdaCL.Base.Object with record
114 Self : Instance_Access;
115 end record with
116 Put_Image => Object_Image;
117
118 procedure Object_Image (Output : in out Ada.Strings.Text_Buffers.Root_Buffer_Type'Class; This : Object);
119
120 ---
121 -- Called when creating an object
122 --
123 --: @param This Object itself.
124 overriding procedure Initialize (This : in out Object);
125
126 ---
127 -- When asjusting we need hand over the pointer
128 --
129 --: @param This Object itself.
130 overriding procedure Adjust (This : in out Object);
131
132 ---
133 -- When finalizing we need delete the pointer
134 --
135 --: @param This Object itself.
136 overriding procedure Finalize (This : in out Object);
137
138 ---
139 -- checks whether the managed object is managed only by the current shared_ptr instance
140 --
141 --: @return true when use counter is one.
142 function Unique (This : in Object) return Boolean is (This.Use_Count = 1);
143
144end AdaCL.Pointer.Shared_With_Delete;
145
146---------------------------------------------------------------- {{{ ----------
147--: vim: set textwidth=0 nowrap tabstop=8 shiftwidth=3 softtabstop=3 expandtab :
148--: vim: set filetype=ada fileencoding=utf-8 fileformat=unix foldmethod=expr :
149--: vim: set spell spelllang=en_gb :