intmap 2.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126
  1. .TH INTMAP 2
  2. .SH NAME
  3. Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey,
  4. deletekey \- integer to data structure maps
  5. .SH SYNOPSIS
  6. .ft L
  7. .nf
  8. #include <u.h>
  9. #include <libc.h>
  10. #include <fcall.h>
  11. #include <thread.h>
  12. #include <9p.h>
  13. .fi
  14. .PP
  15. .ft L
  16. .nf
  17. .ta \w'\fLIntmap* 'u
  18. Intmap* allocmap(void (*inc)(void*))
  19. void freemap(Intmap *map, void (*dec)(void*))
  20. void* lookupkey(Intmap *map, ulong key)
  21. void* insertkey(Intmap *map, ulong key, void *val)
  22. int caninsertkey(Intmap *map, ulong key, void *val)
  23. void* lookupkey(Intmap *map, ulong key)
  24. void* deletekey(Intmap *map, ulong key)
  25. .fi
  26. .SH DESCRIPTION
  27. An
  28. .B Intmap
  29. is an arbitrary mapping from integers to pointers.
  30. .I Allocmap
  31. creates a new map, and
  32. .I freemap
  33. destroys it.
  34. The
  35. .I inc
  36. function is called each time a new pointer is added
  37. to the map; similarly,
  38. .I dec
  39. is called on each pointer left in the map
  40. when it is being freed.
  41. Typically these functions maintain reference counts.
  42. New entries are added to the map by calling
  43. .IR insertkey ,
  44. which will return the previous value
  45. associated with the given
  46. .IR key ,
  47. or zero if there was no previous value.
  48. .I Caninsertkey
  49. is like
  50. .I insertkey
  51. but only inserts
  52. .I val
  53. if there is no current mapping.
  54. It returns 1 if
  55. .I val
  56. was inserted, 0 otherwise.
  57. .I Lookupkey
  58. returns the pointer associated with
  59. .IR key ,
  60. or zero if there is no such pointer.
  61. .I Deletekey
  62. removes the entry for
  63. .I id
  64. from the map, returning the
  65. associated pointer, if any.
  66. .PP
  67. Concurrent access to
  68. .BR Intmap s
  69. is safe,
  70. moderated via a
  71. .B QLock
  72. stored in the
  73. .B Intmap
  74. structure.
  75. .PP
  76. In anticipation of the storage of reference-counted
  77. structures, an increment function
  78. .I inc
  79. may be specified
  80. at map creation time.
  81. .I Lookupkey
  82. calls
  83. .I inc
  84. (if non-zero)
  85. on pointers before returning them.
  86. If the reference count adjustments were
  87. left to the caller (and thus not protected by the lock),
  88. it would be possible to accidentally reclaim a structure
  89. if, for example, it was deleted from the map and its
  90. reference count decremented between the return
  91. of
  92. .I insertkey
  93. and the external increment.
  94. .IR Insertkey
  95. and
  96. .IR caninsertkey
  97. do
  98. .I not
  99. call
  100. .I inc
  101. when inserting
  102. .I val
  103. into the map, nor do
  104. .I insertkey
  105. or
  106. .I deletekey
  107. call
  108. .I inc
  109. when returning old map entries.
  110. The rationale is that calling
  111. an insertion function transfers responsibility for the reference
  112. to the map, and responsibility is given back via the return value of
  113. .I deletekey
  114. or the next
  115. .IR insertkey .
  116. .PP
  117. .BR Intmap s
  118. are used by the 9P library to implement
  119. .BR Fidpool s
  120. and
  121. .BR Reqpool s.
  122. .SH SOURCE
  123. .B /sys/src/lib9p/intmap.c
  124. .SH SEE ALSO
  125. .IR 9p (2),
  126. .IR 9pfid (2).