You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/manual/cache/KeyPgCallocate.wakka
+5-8Lines changed: 5 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ Allocates memory for a certain number of elements from the free store and clears
22
22
Similarly, ##**Callocate**## can also be used directly with ##[[KeyPgZstring|Zstring]]## or ##[[KeyPgWstring|Wstring]]## because string data is created with null characters.
When memory was allocated to hold a string descriptor, the string must always be destroyed (setting to ##"####"##) before deallocate the string descriptor (allowing to deallocate the memory taken up by the string data), otherwise, it is not possible to deallocate it later, and it may induce memory leak in the program continuation.
18
18
19
19
Calling **##Deallocate##** on a null pointer induces no action.
20
-
21
-
~&**##Deallocate##** is an alias for the C runtime library's **##free##**, so it's not guaranteed to be thread safe in all platforms.
22
20
23
21
{{fbdoc item="ex"}}
24
-
The following example shows how to free previously allocated memory. Note that the pointer is set to null following the deallocation:
dim as integer ptr integerPtr = allocate( len( integer ) ) '' initialize pointer to
29
26
'' new memory address
@@ -37,13 +34,12 @@ end sub
37
34
38
35
DeallocateExample1()
39
36
end 0
40
-
%%
41
-
42
-
Although in this case it is unnecessary since the function immediately exits afterwards, setting the pointer to null is a good habit to get into. If the function deallocated memory from a pointer that was passed in by reference, for instance, the pointer that was used in the function call will be rendered invalid, and it is up to the caller to either reassign the pointer or set it to null. Example 3 shows how to correctly handle this kind of situation, and the next example shows the effects of deallocating memory with multiple references.
43
-
44
-
In the following example, a different pointer is used to free previously allocated memory.
Although in this case it is unnecessary since the function immediately exits afterwards, setting the pointer to null is a good habit to get into. If the function deallocated memory from a pointer that was passed in by reference, for instance, the pointer that was used in the function call will be rendered invalid, and it is up to the caller to either reassign the pointer or set it to null. Example 3 shows how to correctly handle this kind of situation, and the next example shows the effects of deallocating memory with multiple references.
40
+
41
+
In the following example, a different pointer is used to free previously allocated memory:
'' WARNING: "evil" example showing how things should NOT be done
48
44
49
45
sub DeallocateExample2()
@@ -65,11 +61,11 @@ end sub
65
61
66
62
DeallocateExample2()
67
63
end 0
68
-
%%
69
-
70
-
Note that after the deallocation, //both// pointers are rendered invalid. This illustrates another one of the ways that bugs can arise when working with pointers. As a general rule, only deallocate memory previously allocated when you know that there is only one (1) pointer currently pointing at it.
Note that after the deallocation, //both// pointers are rendered invalid. This illustrates another one of the ways that bugs can arise when working with pointers. As a general rule, only deallocate memory previously allocated when you know that there is only one (1) pointer currently pointing at it.
In the program above, a reference pointer in a function is set to null after deallocating the memory it points to. An ##[[KeyPgAssert|ASSERT]]## macro is used to test if the original pointer is in fact null after the function call. This example implies the correct way to pass pointers to functions that deallocate the memory they point to is by reference.
93
+
In the program above, a reference pointer in a function is set to null after deallocating the memory it points to. An ##[[KeyPgAssert|ASSERT]]## macro is used to test if the original pointer is in fact null after the function call. This example implies the correct way to pass pointers to functions that deallocate the memory they point to is by reference.
98
94
99
95
{{fbdoc item="lang"}}
100
96
- Not available in the //[[CompilerOptlang|-lang qb]]// dialect unless referenced with the alias ##**""__Deallocate""**##.
A ##[[KeyPgString|string]]## containing the filename of the library to load.
11
+
##//libname//##
12
+
A ##[[KeyPgString|string]]## containing the name of the library to load.
13
13
14
14
{{fbdoc item="ret"}}
15
15
The ##[[KeyPgPtr|pointer]]## handle of the library loaded. Zero on error
16
16
17
17
{{fbdoc item="desc"}}
18
18
##[[KeyPgDylibload|Dylibload]]## is used to link at runtime libraries to your program. This function does the link and returns a handle that must be used with ##[[KeyPgDylibsymbol|Dylibsymbol]]## when calling a function in the library and with ##[[KeyPgDylibfree|Dylibfree]]## when releasing the library.
19
19
20
-
Note: If the ##//filename//## string (without extension) already includes a character dot (##.##), it may be mandatory to explicitly specify the filename extension to avoid any parser ambiguity.
20
+
Note: If the ##//libname//## string (without extension) already includes a character dot (##.##), it may be mandatory to explicitly specify the filename extension to avoid any parser ambiguity.
21
21
22
22
{{fbdoc item="ex"}}
23
23
See the dynamic loading example on the [[ProPgSharedLibraries|Shared Libraries]] page.
The [[KeyPgAny|any]] [[KeyPgPtr|ptr]] handle of a DLL returned by ##[[KeyPgDylibload|Dylibload]]##
14
14
##//symbol//##
15
15
A [[KeyPgString|string]] containing name of the function, or variable in the library to return the address of. In Windows only, can also be a ##[[KeyPgShort|short]]## containing the ordinal of the function/variable.
0 commit comments