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