1# SendableLruCache<K, V> 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @lijiamin2025--> 5<!--Designer: @weng-changcheng--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8 9SendableLruCache在缓存空间不足时，会用新数据替换近期最少使用的数据。此设计基于资源访问的考虑：近期访问的数据可能在不久的将来再次访问，因此最少访问的数据价值最小，应优先移出缓存。SendableLruCache支持Sendable特性，可保存Sendable对象，确保跨线程安全访问。 10 11> **说明：** 12> 13> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> SendableLruCache首批接口从API version 18开始支持。 16> 17> 此模块仅支持在ArkTS文件（文件后缀为.ets）中导入使用。 18 19## 导入模块 20 21```ts 22import { ArkTSUtils } from '@kit.ArkTS' 23``` 24 25## 属性 26 27**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.Utils.Lang 30 31| 名称 | 类型 | 只读 | 可选 | 说明 | 32| ------ | ------ | ---- | ---- | ---------------------- | 33| length<sup>18+</sup> | number | 是 | 否 | 当前缓冲区中值的总数。 | 34 35**示例：** 36 37```ts 38let pro = new ArkTSUtils.SendableLruCache<number, number>(); 39pro.put(2, 10); 40pro.put(1, 8); 41let result = pro.length; 42console.info('result = ' + result); 43// 期望输出：result = 2 44``` 45 46## constructor<sup>18+</sup> 47 48constructor(capacity?: number) 49 50默认构造函数用于创建一个新的SendableLruCache实例，默认容量为64。 51 52**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.Utils.Lang 55 56**参数：** 57 58| 参数名 | 类型 | 必填 | 说明 | 59| -------- | ------ | ---- | ---------------------------- | 60| capacity | number | 否 | 指示缓冲区的自定义容量。不传时，默认值为64，最大值不能超过2147483647；小于等于0时会抛出异常。 | 61 62**错误码：** 63 64以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 65 66| 错误码ID | 错误信息 | 67| -------- | ------------------------------------------| 68| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 69 70**示例：** 71 72```ts 73let pro = new ArkTSUtils.SendableLruCache<number, number>(); 74``` 75 76## updateCapacity<sup>18+</sup> 77 78updateCapacity(newCapacity: number): void 79 80将缓冲区容量设置为指定值。如果缓冲区中值的总数超过指定容量，将删除最少使用的键值对。 81 82**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.Utils.Lang 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ----------- | ------ | ---- | ---------------------------- | 90| newCapacity | number | 是 | 指示要为缓冲区自定义的容量，最大值不能超过2147483647；小于等于0时会抛出异常。| 91 92**错误码：** 93 94以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 95 96| 错误码ID | 错误信息 | 97| -------- | ------------------------------------------| 98| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 99 100**示例：** 101 102```ts 103let pro = new ArkTSUtils.SendableLruCache<number, number>(); 104pro.updateCapacity(100); 105``` 106 107## toString<sup>18+</sup> 108 109toString(): string 110 111返回对象的字符串表示形式。 112 113**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 114 115**系统能力：** SystemCapability.Utils.Lang 116 117**返回值：** 118 119| 类型 | 说明 | 120| ------ | -------------------------- | 121| string | 返回对象的字符串表示形式。 返回字符串格式是：SendableLruCache[ maxSize = (maxSize), hits = (hitCount), misses = (missCount), hitRate = (hitRate) ]。 (maxSize)表示缓存区最大值，(hitCount)表示查询值匹配成功的次数，(missCount)表示查询值匹配失败的次数，(hitRate)表示查询值匹配率。| 122 123**示例：** 124 125```ts 126let pro = new ArkTSUtils.SendableLruCache<number, number>(); 127pro.put(2, 10); 128pro.get(2); 129pro.get(3); 130console.info(pro.toString()); 131// 预期输出：SendableLruCache[ maxSize = 64, hits = 1, misses = 1, hitRate = 50% ] 132// maxSize: 缓存区最大值 hits: 查询值匹配成功的次数 misses: 查询值匹配失败的次数 hitRate: 查询值匹配率 133``` 134 135## getCapacity<sup>18+</sup> 136 137getCapacity(): number 138 139获取当前缓冲区的容量。 140 141**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 142 143**系统能力：** SystemCapability.Utils.Lang 144 145**返回值：** 146 147| 类型 | 说明 | 148| ------ | ---------------------- | 149| number | 返回当前缓冲区的容量。 | 150 151**示例：** 152 153```ts 154let pro = new ArkTSUtils.SendableLruCache<number, number>(); 155let result = pro.getCapacity(); 156console.info('result = ' + result); 157// 预期输出：result = 64 158``` 159 160## clear<sup>18+</sup> 161 162clear(): void 163 164从当前缓冲区清除所有键值对。 165 166**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 167 168**系统能力：** SystemCapability.Utils.Lang 169 170**示例：** 171 172```ts 173let pro = new ArkTSUtils.SendableLruCache<number, number>(); 174pro.put(2, 10); 175let result = pro.length; 176pro.clear(); 177let res = pro.length; 178console.info('result = ' + result); 179console.info('res = ' + res); 180// 预期输出：result = 1 181// 预期输出：res = 0 182``` 183 184## getCreateCount<sup>18+</sup> 185 186getCreateCount(): number 187 188获取调用内部默认接口创建对象的次数。 189 190**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.Utils.Lang 193 194**返回值：** 195 196| 类型 | 说明 | 197| ------ | -------------------| 198| number | 返回使用内部默认接口创建对象的次数。 | 199 200**示例：** 201 202```ts 203@Sendable 204class ChildLRUCache extends ArkTSUtils.SendableLruCache<number, number> { 205 constructor() { 206 super(); 207 } 208 createDefault(key: number): number { 209 return key; 210 } 211} 212 213let lru = new ChildLRUCache(); 214lru.put(2, 10); 215lru.get(3); 216lru.get(5); 217let res = lru.getCreateCount(); 218console.info('res = ' + res); 219// 预期输出：res = 2 220// 执行get操作时，如果键值不存在，调用createDefault接口判断返回值是否等于undefined 221// 如果不等于，则需要把key和返回值作为键值对添加到cache中，并且创建次数加1 222``` 223 224## getMissCount<sup>18+</sup> 225 226getMissCount(): number 227 228获取查询值不匹配的次数。 229 230**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 231 232**系统能力：** SystemCapability.Utils.Lang 233 234**返回值：** 235 236| 类型 | 说明 | 237| ------ | ------------------------ | 238| number | 返回查询值不匹配的次数。 | 239 240**示例：** 241 242```ts 243let pro = new ArkTSUtils.SendableLruCache<number, number>(); 244pro.put(2, 10); 245pro.get(2); 246let result = pro.getMissCount(); 247console.info('result = ' + result); 248// 预期输出：result = 0 249``` 250 251## getRemoveCount<sup>18+</sup> 252 253getRemoveCount(): number 254 255获取缓冲区键值对的回收次数。当缓冲区数量超过容量限制时，最少使用的键值对将被回收。 256 257**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 258 259**系统能力：** SystemCapability.Utils.Lang 260 261**返回值：** 262 263| 类型 | 说明 | 264| ------ | -------------------------- | 265| number | 返回缓冲区键值对回收的次数。 | 266 267**示例：** 268 269```ts 270let pro = new ArkTSUtils.SendableLruCache<number, number>(); 271pro.put(2, 10); 272pro.updateCapacity(2); 273pro.put(50, 22); 274let result = pro.getRemoveCount(); 275console.info('result = ' + result); 276// 预期输出：result = 0 277``` 278 279## getMatchCount<sup>18+</sup> 280 281getMatchCount(): number 282 283获取查询值匹配成功的次数。 284 285**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 286 287**系统能力：** SystemCapability.Utils.Lang 288 289**返回值：** 290 291| 类型 | 说明 | 292| ------ | -------------------------- | 293| number | 返回查询值匹配成功的次数。 | 294 295**示例：** 296 297```ts 298let pro = new ArkTSUtils.SendableLruCache<number, number>(); 299pro.put(2, 10); 300pro.get(2); 301let result = pro.getMatchCount(); 302console.info('result = ' + result); 303// 预期输出：result = 1 304``` 305 306## getPutCount<sup>18+</sup> 307 308getPutCount(): number 309 310获取将值添加到缓冲区的次数。 311 312**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 313 314**系统能力：** SystemCapability.Utils.Lang 315 316**返回值：** 317 318| 类型 | 说明 | 319| ------ | ---------------------------- | 320| number | 返回将值添加到缓冲区的次数。 | 321 322**示例：** 323 324```ts 325let pro = new ArkTSUtils.SendableLruCache<number, number>(); 326pro.put(2, 10); 327let result = pro.getPutCount(); 328console.info('result = ' + result); 329// 预期输出：result = 1 330``` 331 332## isEmpty<sup>18+</sup> 333 334isEmpty(): boolean 335 336检查当前缓冲区是否为空。 337 338**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 339 340**系统能力：** SystemCapability.Utils.Lang 341 342**返回值：** 343 344| 类型 | 说明 | 345| ------- | ---------------------------------------- | 346| boolean | 返回true表示当前缓冲区为空，不包含任何键值对；返回false表示当前缓冲区不为空。 | 347 348**示例：** 349 350```ts 351let pro = new ArkTSUtils.SendableLruCache<number, number>(); 352pro.put(2, 10); 353let result = pro.isEmpty(); 354console.info('result = ' + result); 355// 预期输出：result = false 356``` 357 358## get<sup>18+</sup> 359 360get(key: K): V | undefined 361 362返回键对应的值。 363 364**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 365 366**系统能力：** SystemCapability.Utils.Lang 367 368**参数：** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| ------ | ---- | ---- | ------------ | 372| key | K | 是 | 要查询的键。 | 373 374**返回值：** 375 376| 类型 | 说明 | 377| ------------------------ | ------------------------------------------------------------ | 378| V \| undefined | 如果指定的键存在于缓冲区中，则返回与键关联的值；否则调用内部默认接口，生成一个键与值相同的对象，并返回其值。如果内部默认接口返回undefined，则最终返回undefined。 | 379 380**示例：** 381 382```ts 383let pro = new ArkTSUtils.SendableLruCache<number, number>(); 384pro.put(2, 10); 385let result = pro.get(2); 386console.info('result = ' + result); 387// 预期输出：result = 10 388``` 389 390## put<sup>18+</sup> 391 392put(key: K,value: V): V 393 394将键值对添加到缓冲区，并返回与添加的键关联的值。当缓冲区中值的数量超过容量时，会执行删除操作。 395 396**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 397 398**系统能力：** SystemCapability.Utils.Lang 399 400**参数：** 401 402| 参数名 | 类型 | 必填 | 说明 | 403| ------ | ---- | ---- | -------------------------- | 404| key | K | 是 | 要添加的键。 | 405| value | V | 是 | 与要添加的键关联的值。 | 406 407**返回值：** 408 409| 类型 | 说明 | 410| ---- | ------------------------------------------------------------ | 411| V | 返回与添加的键关联的值。| 412 413**示例：** 414 415```ts 416let pro = new ArkTSUtils.SendableLruCache<number, number>(); 417let result = pro.put(2, 10); 418console.info('result = ' + result); 419// 预期输出：result = 10 420``` 421 422## values<sup>18+</sup> 423 424values(): V[] 425 426获取当前缓冲区中所有值的列表，按从最近访问到最少访问的顺序排列，最近访问的键值对表示有最新操作。 427 428**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 429 430**系统能力：** SystemCapability.Utils.Lang 431 432**返回值：** 433 434| 类型 | 说明 | 435| --------- | ------------------------------------------------------------ | 436| V [] | 返回当前缓冲区中所有值的列表，按从最近访问到最少访问的顺序排列。 | 437 438**示例：** 439 440```ts 441let pro = new ArkTSUtils.SendableLruCache<number|string,number|string>(); 442pro.put(2, 10); 443pro.put(2, "anhu"); 444pro.put("afaf", "grfb"); 445let result = pro.values(); 446console.info('result = ' + result); 447// 预期输出：result = anhu,grfb 448``` 449 450## keys<sup>18+</sup> 451 452keys(): K[] 453 454获取当前缓冲区中所有键，按从最近访问到最少访问的顺序排列。 455 456**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 457 458**系统能力：** SystemCapability.Utils.Lang 459 460**返回值：** 461 462| 类型 | 说明 | 463| --------- | ------------------------------------------------------------ | 464| K [] | 返回当前缓冲区中所有键的列表，按从最近访问到最少访问的顺序排列。 | 465 466**示例：** 467 468```ts 469let pro = new ArkTSUtils.SendableLruCache<number, number>(); 470pro.put(2, 10); 471pro.put(3, 1); 472let result = pro.keys(); 473console.info('result = ' + result); 474// 预期输出：result = 2,3 475``` 476 477## remove<sup>18+</sup> 478 479remove(key: K): V | undefined 480 481从当前缓冲区中删除指定键及其关联值，返回该键关联的值。若键不存在，则返回undefined。 482 483**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 484 485**系统能力：** SystemCapability.Utils.Lang 486 487**参数：** 488 489| 参数名 | 类型 | 必填 | 说明 | 490| ------ | ---- | ---- | -------------- | 491| key | K | 是 | 要删除的键值。 | 492 493**返回值：** 494 495| 类型 | 说明 | 496| ------------------------ | ------------------------------------------------------------ | 497| V \| undefined | 返回一个包含已删除键值对的Optional对象；如果key不存在，则返回undefined，如果key为null，则抛出异常。 | 498 499**示例：** 500 501```ts 502let pro = new ArkTSUtils.SendableLruCache<number, number>(); 503pro.put(2, 10); 504let result = pro.remove(20); 505console.info('result = ' + result); 506// 预期输出：result = undefined 507``` 508 509## contains<sup>18+</sup> 510 511contains(key: K): boolean 512 513检查当前缓冲区是否包含指定的键，如果存在，返回true；否则，返回false。 514 515**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 516 517**系统能力：** SystemCapability.Utils.Lang 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| ------ | ------ | ---- | ---------------- | 523| key | K | 是 | 表示要检查的键。 | 524 525**返回值：** 526 527| 类型 | 说明 | 528| ------- | ------------------------------------------ | 529| boolean | 如果缓冲区包含指定的键，则返回true，否则返回false。 | 530 531**示例：** 532 533```ts 534let pro = new ArkTSUtils.SendableLruCache<number, number>(); 535pro.put(2, 10); 536let result = pro.contains(2); 537console.info('result = ' + result); 538// 预期输出：result = true 539``` 540 541## entries<sup>18+</sup> 542 543entries(): IterableIterator<[K,V]> 544 545允许迭代包含在这个对象中的所有键值对。 546 547**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 548 549**系统能力：** SystemCapability.Utils.Lang 550 551**返回值：** 552 553| 类型 | 说明 | 554| ----------- | -------------------- | 555| IterableIterator<[K, V]> | 返回一个可迭代数组。 | 556 557**示例：** 558 559```ts 560let pro = new ArkTSUtils.SendableLruCache<number, number>(); 561pro.put(2, 10); 562pro.put(3, 15); 563let pair:Iterable<Object[]> = pro.entries(); 564let arrayValue = Array.from(pair); 565for (let value of arrayValue) { 566 console.info(value[0]+ ', '+ value[1]); 567 // 预期输出： 568 // 2, 10 569 // 3, 15 570} 571```