1/* 2 * Copyright (c) 2021-2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16package std.core; 17 18/** 19 * @class GC defines methods with GC-specific behavior 20 */ 21export namespace GC { 22 /** 23 * @see getObjectSpaceType 24 */ 25 export enum ObjectSpaceType { 26 OBJECT = 1, 27 HUMONGOUS = 2, 28 NON_MOVABLE = 3, 29 YOUNG = 4, 30 TENURED = 5 31 } 32 33 /** 34 * @see startGC 35 * @see scheduleGcAfterNthAlloc 36 */ 37 export enum Cause { 38 YOUNG = 0, 39 THRESHOLD = 1, 40 MIXED = 2, 41 FULL = 3 42 } 43 44 export const NOT_IN_PLACE_MODE: boolean = false; 45 export const IN_PLACE_MODE: boolean = true; 46 47 48 /** 49 * @returns long - free heap space in bytes available for new objects 50 */ 51 export native function getFreeHeapSize(): long; 52 53 /** 54 * @returns long - currently used heap space in bytes 55 */ 56 export native function getUsedHeapSize(): long; 57 58 /** 59 * @returns long - maximum heap space size in bytes 60 */ 61 export native function getReservedHeapSize(): long; 62 63 /** 64 * The function triggers specific GC 65 * 66 * @param cause cause of requested GC 67 * @param callback callback is called in concurrent phase 68 * @param inPlaceMode run GC in place mode 69 * 70 * @throws IllegalArgumentException if current GC does not support requested cause 71 * 72 * @returns id of started GC. 73 * - The id can be passed to waitForFinishGC to ensure the GC is finished. 74 * - 0 in case the GC is executed in-place. It means there is no need to wait such GC 75 * - -1 in case the task is canceled 76 */ 77 export function startGC(cause: Cause, callback: () => void, inPlaceMode: boolean = GC.NOT_IN_PLACE_MODE): long { 78 return startGCImpl(cause as int, callback as Object, inPlaceMode); 79 } 80 81 /** 82 * The function triggers specific GC 83 * 84 * @param cause cause of requested GC 85 * @param inPlaceMode run GC in place mode 86 * 87 * @throws IllegalArgumentException if current GC does not support requested cause 88 * @throws UnsupportedOperationException if current GC does not support requested cause 89 * @throws IllegalStateException if try to run threshold GC collection not in place after calling postponeGCStart 90 * 91 * @returns id of started GC. 92 * - The id can be passed to waitForFinishGC to ensure the GC is finished. 93 * - 0 in case the GC is executed in-place. It means there is no need to wait such GC 94 * - -1 in case the task is canceled. 95 */ 96 export function startGC(cause: Cause, inPlaceMode: boolean = GC.NOT_IN_PLACE_MODE): long { 97 return startGCImpl(cause as int, undefined, inPlaceMode); 98 } 99 100 native function startGCImpl(cause: int, callback: Object | undefined, runInPlace: boolean): long throws; 101 102 /** 103 * The function returns when the specified GC gets finished 104 * 105 * @param gcId id of the GC which is returned by startGC. 106 * If gcId is 0 or -1 the function returns immediately. 107 */ 108 export native function waitForFinishGC(gcId: long): void; 109 110 /** 111 * Method schedules GC before n-th allocation by setting counter to the specific GC trigger 112 * Another call may reset the counter. In this case the last counter will be used to trigger the GC. 113 * 114 * @param counter number of allocation for trigger GC 115 * @param cause cause of requested GC 116 * 117 * @throws IllegalArgumentException if current GC does not support requested cause 118 * @throws UnsupportedOperationException if VM is running with incorrect GC trigger 119 */ 120 native function scheduleGcAfterNthAllocImpl(counter: int, cause: int): void throws; 121 122 export function scheduleGcAfterNthAlloc(counter: int, cause: Cause) { 123 scheduleGcAfterNthAllocImpl(counter, cause as int); 124 } 125 126 /** 127 * Checks if GC was triggered 128 * 129 * @returns true if scheduled GC was triggered for a n-th allocation, false - otherwise 130 * 131 * @see scheduleGcAfterNthAlloc 132 */ 133 export native function isScheduledGCTriggered(): boolean; 134 135 /** 136 * Start postponing GC collection - postpone GC for some time. 137 * Disable threshold collections, young collections will promote everything. 138 * Require to run postponeGCEnd after finishing critical code. 139 * 140 * @see postponeGCEnd 141 * 142 * @throws UnsupportedOperationException if GC doesn't support postponing 143 * @throws IllegalStateException if it called after calling postponeGCStart 144 * without calling postponeGCEnd 145 */ 146 export native function postponeGCStart(): void; 147 148 /** 149 * End postponing GC collection - finish postpone GC collections. 150 * Should be called after postponeGCStart 151 * 152 * @see postponeGCStart 153 * 154 * @throws UnsupportedOperationException if GC doesn't support postponing 155 * @throws IllegalStateException if it called without calling postponeGCStart 156 */ 157 export native function postponeGCEnd(): void; 158 159 /** 160 * Pin object - GC will not move pinned object 161 * 162 * @param obj non-pinned object for pinning 163 * 164 * @see unpinObject 165 * 166 * @throws UnsupportedOperationException if used GC does not support pinning 167 */ 168 export native function pinObject(obj: Object): void throws; 169 170 /** 171 * Unpin pinned object - now GC can move such object if it need 172 * 173 * @note Unpinning of non-pinned object is unspecified behavior 174 * 175 * @see pinObject 176 * @see allocatePinned<PrimitiveType>Array 177 * 178 * @param obj pinned object for unpinning 179 */ 180 export native function unpinObject(obj: Object): void; 181 182 /** 183 * Allocate array of boolean and pin (GC will not move pinned array) 184 * 185 * @param length count of array elements 186 * 187 * @see unpinObject 188 * 189 * @throws NegativeArraySizeError if length is negative 190 * @throws UnsupportedOperationException if used GC does not support pinning 191 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 192 * 193 * @returns pinned array of boolean 194 */ 195 export native function allocatePinnedBooleanArray(length: long): FixedArray<boolean> throws; 196 197 /** 198 * Allocate array of byte and pin (GC will not move pinned array) 199 * 200 * @param length count of array elements 201 * 202 * @see unpinObject 203 * 204 * @throws NegativeArraySizeError if length is negative 205 * @throws UnsupportedOperationException if used GC does not support pinning 206 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 207 * 208 * @returns pinned array of byte 209 */ 210 export native function allocatePinnedByteArray(length: long): FixedArray<byte> throws; 211 212 /** 213 * Allocate array of char and pin (GC will not move pinned array) 214 * 215 * @param length count of array elements 216 * 217 * @see unpinObject 218 * 219 * @throws NegativeArraySizeError if length is negative 220 * @throws UnsupportedOperationException if used GC does not support pinning 221 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 222 * 223 * @returns pinned array of char 224 */ 225 export native function allocatePinnedCharArray(length: long): FixedArray<char> throws; 226 227 /** 228 * Allocate array of short and pin (GC will not move pinned array) 229 * 230 * @param length count of array elements 231 * 232 * @see unpinObject 233 * 234 * @throws NegativeArraySizeError if length is negative 235 * @throws UnsupportedOperationException if used GC does not support pinning 236 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 237 * 238 * @returns pinned array of short 239 */ 240 export native function allocatePinnedShortArray(length: long): FixedArray<short> throws; 241 242 /** 243 * Allocate array of int and pin (GC will not move pinned array) 244 * 245 * @param length count of array elements 246 * 247 * @see unpinObject 248 * 249 * @throws NegativeArraySizeError if length is negative 250 * @throws UnsupportedOperationException if used GC does not support pinning 251 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 252 * 253 * @returns pinned array of int 254 */ 255 export native function allocatePinnedIntArray(length: long): FixedArray<int> throws; 256 257 /** 258 * Allocate array of long and pin (GC will not move pinned array) 259 * 260 * @param length count of array elements 261 * 262 * @see unpinObject 263 * 264 * @throws NegativeArraySizeError if length is negative 265 * @throws UnsupportedOperationException if used GC does not support pinning 266 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 267 * 268 * @returns pinned array of long 269 */ 270 export native function allocatePinnedLongArray(length: long): FixedArray<long> throws; 271 272 /** 273 * Allocate array of float and pin (GC will not move pinned array) 274 * 275 * @param length count of array elements 276 * 277 * @see unpinObject 278 * 279 * @throws NegativeArraySizeError if length is negative 280 * @throws UnsupportedOperationException if used GC does not support pinning 281 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 282 * 283 * @returns pinned array of float 284 */ 285 export native function allocatePinnedFloatArray(length: long): FixedArray<float> throws; 286 287 /** 288 * Allocate array of double and pin (GC will not move pinned array) 289 * 290 * @param length count of array elements 291 * 292 * @see unpinObject 293 * 294 * @throws NegativeArraySizeError if length is negative 295 * @throws UnsupportedOperationException if used GC does not support pinning 296 * @throws OutOfMemoryError if VM has not enough heap space for array allocation 297 * 298 * @returns pinned array of double 299 */ 300 export native function allocatePinnedDoubleArray(length: long): FixedArray<double> throws; 301 302 /** 303 * Returns encoded space type 304 * 305 * @param obj object for which space type is requested 306 * 307 * @returns type of space which contains object-argument 308 */ 309 native function getObjectSpaceTypeImpl(obj: Object): int; 310 311 export function getObjectSpaceType(obj: Object): ObjectSpaceType { 312 let spaceType: int = getObjectSpaceTypeImpl(obj); 313 return spaceType as ObjectSpaceType; 314 } 315 316 /** 317 * Returns object address 318 * 319 * @param obj object for which address is requested 320 * 321 * @returns address of object 322 */ 323 export native function getObjectAddress(obj: Object): long; 324 325 /** 326 * @param obj object for which size is requested 327 * @returns size of the object in bytes 328 */ 329 export native function getObjectSize(obj: Object): long; 330 331 /** 332 * @throws NegativeArraySizeError if size is negative 333 * 334 * @param size: long - number of bytes to be registered by GC as native 335 */ 336 export native function registerNativeAllocation(size: long): void; 337 338 /** 339 * @throws NegativeArraySizeError if size is negative 340 * 341 * @param size: long - number of bytes to be freed by GC 342 */ 343 export native function registerNativeFree(size: long): void; 344} 345