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