root/trunk/umem_cache_create.3

Revision 30, 16.3 kB (checked in by wez, 7 years ago)

add man pages from opensolaris

Line 
1 '\" te
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License"). 
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
21 .TH umem_cache_create 3MALLOC "4 Nov 2003" "SunOS 5.11" "Memory Allocation Library Functions"
22 .SH NAME
23 umem_cache_create, umem_cache_destroy, umem_cache_alloc, umem_cache_free \- allocation cache manipulation
24 .SH SYNOPSIS
25 .LP
26 .nf
27 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ]
28 #include <umem.h>
29
30 \fBumem_cache_t *\fR\fBumem_cache_create\fR(\fBchar *\fR\fIdebug_name\fR, \fBsize_t\fR \fIbufsize\fR,
31     \fBsize_t\fR \fIalign\fR, \fBumem_constructor_t *\fR\fIconstructor\fR,
32     \fBumem_destructor_t *\fR\fIdestructor\fR, \fBumem_reclaim_t *\fR\fIreclaim\fR,
33     \fBvoid *\fR\fIcallback_data\fR, \fBvmem_t *\fR\fIsource\fR, \fBint\fR \fIcflags\fR);
34 .fi
35 .LP
36 .nf
37 \fBvoid\fR \fBumem_cache_destroy\fR(\fBumem_cache_t *\fR\fIcache\fR);
38 .fi
39 .LP
40 .nf
41 \fBvoid *\fR\fBumem_cache_alloc\fR(\fBumem_cache_t *\fR\fIcache\fR, \fBint\fR \fIflags\fR);
42 .fi
43 .LP
44 .nf
45 \fBvoid\fR \fBumem_cache_free\fR(\fBumem_cache_t *\fR\fIcache\fR, \fBvoid *\fR\fIbuffer\fR);
46 .fi
47
48 .SH DESCRIPTION
49
50 .LP
51 These functions create, destroy, and use an "object cache".  An object cache is a collection of buffers of a single size, with optional content caching enabled by the use of callbacks (see \fBCache Callbacks\fR).  Object caches are MT-Safe. Multiple allocations and freeing of
52 memory from different threads can proceed simultaneously.  Object caches are faster and use less space per buffer than
53 \fBmalloc\fR(3MALLOC) and
54 \fBumem_alloc\fR(3MALLOC).  For more information about object caching, see "The Slab Allocator: An Object-Caching Kernel Memory Allocator" and "Magazines
55 and vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources".
56 .sp
57
58 .LP
59 The \fBumem_cache_create()\fR function creates object caches. Once a cache has been created, objects can be requested from and returned to the cache using \fBumem_cache_alloc()\fR and \fBumem_cache_free()\fR, respectively. A cache with no outstanding
60 buffers can be destroyed with \fBumem_cache_destroy()\fR.
61 .sp
62
63 .SS Creating and Destroying Caches
64
65 .LP
66 The \fBumem_cache_create()\fR function creates a cache of objects and takes as arguments the following:
67 .sp
68
69 .sp
70 .ne 2
71 .mk
72 .na
73 \fB\fIdebug_name\fR\fR
74 .ad
75 .RS 15n
76 .rt 
77 A human-readable name for debugging purposes.
78 .sp
79
80 .RE
81
82 .sp
83 .ne 2
84 .mk
85 .na
86 \fB\fIbufsize\fR\fR
87 .ad
88 .RS 15n
89 .rt 
90 The size, in bytes, of the buffers in this cache.
91 .sp
92
93 .RE
94
95 .sp
96 .ne 2
97 .mk
98 .na
99 \fB\fIalign\fR\fR
100 .ad
101 .RS 15n
102 .rt 
103 The minimum alignment required for buffers in this cache. This parameter must be a power of 2. If 0, it is replaced with the minimum required alignment for the current architecture.
104 .sp
105
106 .RE
107
108 .sp
109 .ne 2
110 .mk
111 .na
112 \fB\fIconstructor\fR\fR
113 .ad
114 .RS 15n
115 .rt 
116 The callback to construct an object.
117 .sp
118
119 .RE
120
121 .sp
122 .ne 2
123 .mk
124 .na
125 \fB\fIdestructor\fR\fR
126 .ad
127 .RS 15n
128 .rt 
129 The callback to destroy an object.
130 .sp
131
132 .RE
133
134 .sp
135 .ne 2
136 .mk
137 .na
138 \fB\fIreclaim\fR\fR
139 .ad
140 .RS 15n
141 .rt 
142 The callback to reclaim objects.
143 .sp
144
145 .RE
146
147 .sp
148 .ne 2
149 .mk
150 .na
151 \fB\fIcallback_data\fR\fR
152 .ad
153 .RS 15n
154 .rt 
155 An opaque pointer passed to the callbacks.
156 .sp
157
158 .RE
159
160 .sp
161 .ne 2
162 .mk
163 .na
164 \fB\fIsource\fR\fR
165 .ad
166 .RS 15n
167 .rt 
168 This parameter must be \fINULL\fR.
169 .sp
170
171 .RE
172
173 .sp
174 .ne 2
175 .mk
176 .na
177 \fB\fIcflags\fR\fR
178 .ad
179 .RS 15n
180 .rt 
181 This parameter must be either 0 or \fBUMC_NODEBUG\fR. If \fBUMC_NODEBUG\fR, all debugging features are disabled for this cache. See
182 \fBumem_debug\fR(3MALLOC).
183 .sp
184
185 .RE
186
187 .LP
188 Each cache can have up to three associated callbacks:
189 .sp
190
191 .LP
192 .in +2
193 .nf
194 int constructor(void *buffer, void *callback_data, int flags);
195 void destructor(void *buffer, void *callback_data);
196 void reclaim(void *callback_data);
197 .fi
198 .in -2
199
200 .LP
201 The \fIcallback_data\fR argument is always equal to the value passed to \fBumem_cache_create()\fR, thereby allowing a client to use the same callback functions for multiple caches, but with customized behavior.
202 .sp
203
204 .LP
205 The reclaim callback is called when the umem function is requesting more memory from the operating system. This callback can be used by clients who retain objects longer than they are strictly needed (for example, caching non-active state).  A typical reclaim callback might return to the
206 cache ten per cent of the unneeded buffers.
207 .sp
208
209 .LP
210 The constructor and destructor callbacks enable the management of buffers with the constructed state. The constructor takes as arguments a buffer with undefined contents, some callback data, and the flags to use for any allocations. This callback should transform the buffer into the constructed
211 state.
212 .sp
213
214 .LP
215 The destructor callback takes as an argument a constructed object and prepares it for return to the general pool of memory.  The destructor should undo any state that the constructor created.  For debugging, the destructor can also check that the buffer is in the constructed state, to catch
216 incorrectly freed buffers.  See
217 \fBumem_debug\fR(3MALLOC) for further information on debugging support.
218 .sp
219
220 .LP
221 The \fBumem_cache_destroy()\fR function destroys an object cache. If the cache has any outstanding allocations, the behavior is undefined.
222 .sp
223
224 .SS Allocating Objects
225
226 .LP
227 The \fBumem_cache_alloc()\fR function takes as arguments:
228 .sp
229
230 .sp
231 .ne 2
232 .mk
233 .na
234 \fB\fIcache\fR\fR
235 .ad
236 .RS 7n
237 .rt 
238 a cache pointer
239 .sp
240
241 .RE
242
243 .sp
244 .ne 2
245 .mk
246 .na
247 \fB\fIflags\fR\fR
248 .ad
249 .RS 7n
250 .rt 
251 flags that determine the behavior if \fBumem_cache_alloc()\fR is unable to fulfill the allocation request
252 .sp
253
254 .RE
255
256 .LP
257 If successful, \fBumem_cache_alloc()\fR returns a pointer to the beginning of an object of \fIbufsize\fR length.
258 .sp
259
260 .LP
261 There are three cases to consider:
262 .sp
263
264 .sp
265 .RS +4
266 .TP
267 .ie t \(bu
268 .el o
269 A new buffer needed to be allocated. If the cache was created with a constructor, it is applied to the buffer and the resulting object is returned.
270 .sp
271
272 .RE
273
274 .sp
275 .RS +4
276 .TP
277 .ie t \(bu
278 .el o
279 The object cache was able to use a previously freed buffer.  If the cache was created with a constructor, the object is returned unchanged from when it was freed.
280 .sp
281
282 .RE
283
284 .sp
285 .RS +4
286 .TP
287 .ie t \(bu
288 .el o
289 The allocation of a new buffer failed. The \fIflags\fR argument determines the behavior:
290 .sp
291
292 .sp
293 .ne 2
294 .mk
295 .na
296 \fB\fBUMEM_DEFAULT\fR\fR
297 .ad
298 .RS 14n
299 .rt 
300 The \fBumem_cache_alloc()\fR function returns \fINULL\fR if the allocation fails.
301 .sp
302
303 .RE
304
305 .sp
306 .ne 2
307 .mk
308 .na
309 \fB\fBUMEM_NOFAIL\fR\fR
310 .ad
311 .RS 14n
312 .rt 
313 The \fBumem_cache_alloc()\fR function cannot return \fINULL\fR. A callback is used to determine what action occurs. See
314 \fBumem_alloc\fR(3MALLOC) for more information.
315 .sp
316
317 .RE
318
319 .RE
320
321 .SS Freeing Objects
322
323 .LP
324 The \fBumem_cache_free()\fR function takes as arguments:
325 .sp
326
327 .sp
328 .ne 2
329 .mk
330 .na
331 \fB\fIcache\fR\fR
332 .ad
333 .RS 7n
334 .rt 
335 a cache pointer
336 .sp
337
338 .RE
339
340 .sp
341 .ne 2
342 .mk
343 .na
344 \fB\fIbuf\fR\fR
345 .ad
346 .RS 7n
347 .rt 
348 a pointer previously returned from \fBumem_cache_alloc()\fR. This argument must not be \fINULL\fR.
349 .sp
350
351 .RE
352
353 .LP
354 If the cache was created with a constructor callback, the object must be returned to the constructed state before it is freed.
355 .sp
356
357 .LP
358 Undefined behavior results if an object is freed multiple times, if an object is modified after it is freed, or if an object is freed to a cache other than the one from which it was allocated.
359 .sp
360
361 .SS Caches with Constructors
362
363 .LP
364 When a constructor callback is in use, there is essentially a contract between the cache and its clients.  The cache guarantees that all objects returned from \fBumem_cache_alloc()\fR will be in the constructed state, and the client guarantees that it will return the object
365 to the constructed state before handing it to \fBumem_cache_free()\fR.
366 .sp
367
368 .SH RETURN VALUES
369
370 .LP
371 Upon failure, the \fBumem_cache_create()\fR function returns a null pointer.
372 .sp
373
374 .SH ERRORS
375
376 .LP
377 The \fBumem_cache_create()\fR function will fail if:
378 .sp
379
380 .sp
381 .ne 2
382 .mk
383 .na
384 \fB\fBEAGAIN\fR\fR
385 .ad
386 .RS 8n
387 .rt 
388 There is not enough memory available to allocate the cache data structure.
389 .sp
390
391 .RE
392
393 .sp
394 .ne 2
395 .mk
396 .na
397 \fB\fBEINVAL\fR\fR
398 .ad
399 .RS 8n
400 .rt 
401 The \fIdebug_name\fR argument is \fINULL\fR, the \fIalign\fR argument is not a power of two or is larger than the system pagesize, or the \fIbufsize\fR argument is 0.
402 .sp
403
404 .RE
405
406 .sp
407 .ne 2
408 .mk
409 .na
410 \fB\fBENOMEM\fR\fR
411 .ad
412 .RS 8n
413 .rt 
414 The \fBlibumem\fR library could not be initialized, or the \fIbufsize\fR argument is too large and its use would cause integer overflow to occur.
415 .sp
416
417 .RE
418
419 .SH EXAMPLES
420 .LP
421 \fBExample 1 \fRUse a fixed-size structure with no constructor callback.
422
423 .LP
424 .in +2
425 .nf
426 #include <umem.h>
427
428 typedef struct my_obj {
429     long my_data1;
430 } my_obj_t;
431
432 /*
433 * my_objs can be freed at any time.  The contents of
434 * my_data1 is undefined at allocation time.
435 */
436
437 umem_cache_t *my_obj_cache;
438
439 \&...
440 my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),
441    0, NULL, NULL, NULL, NULL, NULL, 0);
442 \&...
443 my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);
444 \&...
445 /* use cur */
446 \&...
447 umem_cache_free(my_obj_cache, cur);
448 \&...
449 .fi
450 .in -2
451 .LP
452 \fBExample 2 \fRUse an object with a mutex.
453
454 .LP
455 .in +2
456 .nf
457 #define _REENTRANT
458 #include <synch.h>
459 #include <umem.h>
460
461 typedef struct my_obj {
462          mutex_t my_mutex;
463          long my_data;
464 } my_obj_t;
465
466 /*
467 * my_objs can only be freed when my_mutex is unlocked.
468 */
469 int
470 my_obj_constructor(void *buf, void *ignored, int flags)
471 {
472          my_obj_t *myobj = buf;
473
474          (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL);
475
476          return (0);
477 }
478
479 void
480 my_obj_destructor(void *buf, void *ignored)
481 {
482          my_obj_t *myobj = buf;
483
484          (void) mutex_destroy(&my_obj->my_mutex);
485 }
486
487 umem_cache_t *my_obj_cache;
488
489 \&...
490 my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),
491    0, my_obj_constructor, my_obj_destructor, NULL, NULL,
492         NULL, 0);
493 \&...
494 my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);
495 cur->my_data = 0;       /* cannot assume anything about my_data */
496 \&...
497 umem_cache_free(my_obj_cache, cur);
498 \&...
499 .fi
500 .in -2
501 .LP
502 \fBExample 3 \fRUse a more complex object with a mutex.
503
504 .LP
505 .in +2
506 .nf
507 #define _REENTRANT
508 #include <assert.h>
509 #include <synch.h>
510 #include <umem.h>
511
512 typedef struct my_obj {
513          mutex_t my_mutex;
514          cond_t my_cv;
515          struct bar *my_barlist;
516          unsigned my_refcount;
517 } my_obj_t;
518
519 /*
520 * my_objs can only be freed when my_barlist == NULL,
521 * my_refcount == 0, there are no waiters on my_cv, and
522 * my_mutex is unlocked.
523 */
524
525 int
526 my_obj_constructor(void *buf, void *ignored, int flags)
527 {
528          my_obj_t *myobj = buf;
529
530          (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL);
531          (void) cond_init(&my_obj->my_cv, USYNC_THREAD, NULL);
532          myobj->my_barlist = NULL;
533          myobj->my_refcount = 0;
534
535          return (0);
536 }
537
538 void
539 my_obj_destructor(void *buf, void *ignored)
540 {
541          my_obj_t *myobj = buf;
542
543          assert(myobj->my_refcount == 0);
544          assert(myobj->my_barlist == NULL);
545          (void) cond_destroy(&my_obj->my_cv);
546          (void) mutex_destroy(&my_obj->my_mutex);
547 }
548
549 umem_cache_t *my_obj_cache;
550
551 \&...
552 my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t),
553    0, my_obj_constructor, my_obj_destructor, NULL, NULL,
554         NULL, 0);
555 \&...
556 my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT);
557 \&...
558 /* use cur */
559 \&...
560 umem_cache_free(my_obj_cache, cur);
561 \&...
562 .fi
563 .in -2
564 .LP
565 \fBExample 4 \fRUse objects with a subordinate buffer while reusing callbacks.
566
567 .LP
568 .in +2
569 .nf
570 #include assert.h>
571 #include umem.h>
572
573 typedef struct my_obj {
574          char *my_buffer;
575          size_t my_size;
576 } my_obj_t;
577
578 /*
579 * my_size and the my_buffer pointer should never be changed
580 */
581
582 int
583 my_obj_constructor(void *buf, void *arg, int flags)
584 {
585          size_t sz = (size_t)arg;
586
587          my_obj_t *myobj = buf;
588
589          if ((myobj->my_buffer = umem_alloc(sz, flags)) == NULL)
590                return (1);
591
592          my_size = sz;
593
594          return (0);
595 }
596
597 void
598 my_obj_destructor(void *buf, void *arg)
599 {
600          size_t sz = (size_t)arg;
601
602          my_obj_t *myobj = buf;
603
604          assert(sz == buf->my_size);
605          umem_free(myobj->my_buffer, sz);
606 }
607
608 \&...
609 umem_cache_t *my_obj_4k_cache;
610 umem_cache_t *my_obj_8k_cache;
611 \&...
612 my_obj_cache_4k = umem_cache_create("my_obj_4k", sizeof (my_obj_t),
613         0, my_obj_constructor, my_obj_destructor, NULL,
614         (void *)4096, NULL, 0);
615
616 my_obj_cache_8k = umem_cache_create("my_obj_8k", sizeof (my_obj_t),
617         0, my_obj_constructor, my_obj_destructor, NULL,
618         (void *)8192, NULL, 0);
619 \&...
620 my_obj_t *my_obj_4k = umem_cache_alloc(my_obj_4k_cache,
621         UMEM_DEFAULT);
622 my_obj_t *my_obj_8k = umem_cache_alloc(my_obj_8k_cache,
623         UMEM_DEFAULT);
624 /* no assumptions should be made about the contents
625 of the buffers */
626 \&...
627 /* make sure to return them to the correct cache */
628 umem_cache_free(my_obj_4k_cache, my_obj_4k);
629 umem_cache_free(my_obj_8k_cache, my_obj_8k);
630 \&...
631 .fi
632 .in -2
633
634 .LP
635 See the \fBEXAMPLES\fR section of
636 \fBumem_alloc\fR(3MALLOC) for examples involving the \fBUMEM_NOFAIL\fR flag.
637 .sp
638
639 .SH ATTRIBUTES
640
641 .LP
642 See
643 \fBattributes\fR(5) for descriptions of the following attributes:
644 .sp
645
646 .LP
647
648 .sp
649 .TS
650 tab() box;
651 cw(2.75i) |cw(2.75i)
652 lw(2.75i) |lw(2.75i)
653 .
654 ATTRIBUTE TYPEATTRIBUTE VALUE
655 _
656 Interface StabilityEvolving
657 _
658 MT-LevelMT-Safe
659 .TE
660
661 .SH SEE ALSO
662
663 .LP
664
665 \fBsetcontext\fR(2),
666 \fBatexit\fR(3C),
667 \fBlibumem\fR(3LIB),
668 \fBlongjmp\fR(3C),
669 \fBswapcontext\fR(3C),
670 \fBthr_exit\fR(3C),
671 \fBumem_alloc\fR(3MALLOC),
672 \fBumem_debug\fR(3MALLOC),
673 \fBattributes\fR(5)
674 .sp
675
676 .LP
677 Bonwick, Jeff, "The Slab Allocator: An Object-Caching Kernel Memory Allocator", Proceedings of the Summer 1994 Usenix Conference.
678 .sp
679
680 .LP
681 Bonwick, Jeff and Jonathan Adams, "Magazines and vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources", Proceedings of the Summer 2001 Usenix Conference.
682 .sp
683
684 .SH WARNINGS
685
686 .LP
687 Any of the following can cause undefined results:
688 .sp
689
690 .sp
691 .RS +4
692 .TP
693 .ie t \(bu
694 .el o
695 Destroying a cache that has outstanding allocated buffers.
696 .sp
697
698 .RE
699
700 .sp
701 .RS +4
702 .TP
703 .ie t \(bu
704 .el o
705 Using a cache after it has been destroyed.
706 .sp
707
708 .RE
709
710 .sp
711 .RS +4
712 .TP
713 .ie t \(bu
714 .el o
715 Calling \fBumem_cache_free()\fR on the same buffer multiple times.
716 .sp
717
718 .RE
719
720 .sp
721 .RS +4
722 .TP
723 .ie t \(bu
724 .el o
725 Passing a \fINULL\fR pointer to \fBumem_cache_free()\fR.
726 .sp
727
728 .RE
729
730 .sp
731 .RS +4
732 .TP
733 .ie t \(bu
734 .el o
735 Writing past the end of a buffer.
736 .sp
737
738 .RE
739
740 .sp
741 .RS +4
742 .TP
743 .ie t \(bu
744 .el o
745 Reading from or writing to a buffer after it has been freed.
746 .sp
747
748 .RE
749
750 .sp
751 .RS +4
752 .TP
753 .ie t \(bu
754 .el o
755 Performing \fBUMEM_NOFAIL\fR allocations from an
756 \fBatexit\fR(3C) handler.
757 .sp
758
759 .RE
760
761 .LP
762 Per-cache callbacks can be called from a variety of contexts. The use of functions that modify the active context, such as
763 \fBsetcontext\fR(2),
764 \fBswapcontext\fR(3C), and
765 \fBthr_exit\fR(3C),
766 or functions that are unsafe for use in multithreaded applications, such as
767 \fBlongjmp\fR(3C) and
768 \fBsiglongjmp\fR(3C), result in undefined behavior.
769 .sp
770
771 .LP
772 A constructor callback that performs allocations must pass its \fIflags\fR argument unchanged to
773 \fBumem_alloc\fR(3MALLOC) and \fBumem_cache_alloc()\fR. Any allocations made with a different flags argument results in undefined behavior.  The constructor must correctly handle the failure of any allocations it makes.
774 .sp
775
776 .SH NOTES
777
778 .LP
779 Object caches make the following guarantees about objects:
780 .sp
781
782 .sp
783 .RS +4
784 .TP
785 .ie t \(bu
786 .el o
787 If the cache has a constructor callback, it is applied to every object before it is returned from \fBumem_cache_alloc()\fR for the first time.
788 .sp
789
790 .RE
791
792 .sp
793 .RS +4
794 .TP
795 .ie t \(bu
796 .el o
797 If the cache has a constructor callback, an object passed to \fBumem_cache_free()\fR and later returned from \fBumem_cache_alloc()\fR is not modified between the two events.
798 .sp
799
800 .RE
801
802 .sp
803 .RS +4
804 .TP
805 .ie t \(bu
806 .el o
807 If the cache has a destructor, it is applied to all objects before their underlying storage is returned.
808 .sp
809
810 .RE
811
812 .LP
813 No other guarantees are made. In particular, even if there are buffers recently freed to the cache, \fBumem_cache_alloc()\fR can fail.
814 .sp
815
Note: See TracBrowser for help on using the browser.