1 '\" te
2 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH KMEM_CACHE_CREATE 9F "Feb 18, 2015"
8 .SH NAME
9 kmem_cache_create, kmem_cache_alloc, kmem_cache_free, kmem_cache_destroy,
10 kmem_cache_set_move \- kernel memory cache allocator operations
11 .SH SYNOPSIS
12 .nf
13 #include <sys/types.h>
14 #include <sys/kmem.h>
15
16 \fBkmem_cache_t *\fR\fBkmem_cache_create\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fIbufsize\fR,
17 \fBsize_t\fR \fIalign\fR, \fBint\fR (*\fIconstructor\fR)(void *, void *, int),
18 \fBvoid\fR (*\fIdestructor\fR)(void *, void *), \fBvoid\fR (*\fIreclaim\fR)(void *),
19 \fBvoid\fR *\fIprivate\fR, \fBvoid\fR *\fIvmp\fR, \fBint\fR \fIcflags\fR);
20 .fi
21
22 .LP
152 .na
153 \fB\fIkmflag\fR\fR
154 .ad
155 .RS 15n
156 Possible flags are:
157 .sp
158 .ne 2
159 .na
160 \fB\fBKM_SLEEP\fR\fR
161 .ad
162 .RS 15n
163 Allow sleeping (blocking) until memory is available.
164 .RE
165
166 .sp
167 .ne 2
168 .na
169 \fB\fBKM_NOSLEEP\fR\fR
170 .ad
171 .RS 15n
172 Return NULL immediately if memory is not available.
173 .RE
174
175 .sp
176 .ne 2
177 .na
178 \fB\fBKM_PUSHPAGE\fR\fR
179 .ad
180 .RS 15n
181 Allow the allocation to use reserved memory.
182 .RE
183
184 .RE
185
186 .sp
187 .ne 2
188 .na
189 \fB\fIobj\fR\fR
190 .ad
191 .RS 15n
192 Pointer to the object allocated by \fBkmem_cache_alloc()\fR.
193 .RE
194
195 .sp
196 .ne 2
197 .na
333 A driver should call \fBkmem_cache_create()\fR at the time of \fB_init\fR(9E)
334 or \fBattach\fR(9E), and call the corresponding \fBkmem_cache_destroy()\fR at
335 the time of \fB_fini\fR(9E) or \fBdetach\fR(9E).
336 .sp
337 .LP
338 \fBkmem_cache_create()\fR creates a cache of objects, each of size
339 \fIbufsize\fR bytes, aligned on an \fIalign\fR boundary. Drivers not requiring
340 a specific alignment can pass 0. \fIname\fR identifies the cache for statistics
341 and debugging. \fIconstructor\fR and \fIdestructor\fR convert plain memory into
342 objects and back again; \fIconstructor\fR can fail if it needs to allocate
343 memory but cannot. \fIprivate\fR is a parameter passed to the constructor and
344 destructor callbacks to support parameterized caches (for example, a pointer to
345 an instance of the driver's soft-state structure). To facilitate debugging,
346 \fBkmem_cache_create()\fR creates a \fBkstat\fR(9S) structure of class
347 \fBkmem_cache\fR and name \fIname\fR. It returns an opaque pointer to the
348 object cache.
349 .sp
350 .LP
351 \fBkmem_cache_alloc()\fR gets an object from the cache. The object will be in
352 its constructed state. \fIkmflag\fR has either \fBKM_SLEEP\fR or
353 \fBKM_NOSLEEP\fR set, indicating whether it is acceptable to wait for memory if
354 none is currently available.
355 .sp
356 .LP
357 A small pool of reserved memory is available to allow the system to progress
358 toward the goal of freeing additional memory while in a low memory situation.
359 The \fBKM_PUSHPAGE\fR flag enables use of this reserved memory pool on an
360 allocation. This flag can be used by drivers that implement \fBstrategy\fR(9E)
361 on memory allocations associated with a single I/O operation. The driver
362 guarantees that the I/O operation will complete (or timeout) and, on
363 completion, that the memory will be returned. The \fBKM_PUSHPAGE\fR flag should
364 be used only in \fBkmem_cache_alloc()\fR calls. All allocations from a given
365 cache should be consistent in their use of the flag. A driver that adheres to
366 these restrictions can guarantee progress in a low memory situation without
367 resorting to complex private allocation and queuing schemes. If
368 \fBKM_PUSHPAGE\fR is specified, \fBKM_SLEEP\fR can also be used without causing
369 deadlock.
370 .sp
371 .LP
372 \fBkmem_cache_free()\fR returns an object to the cache. The object must be in
373 its constructed state.
374 .sp
556 Pointer to the object that has become movable since an earlier refusal to move
557 it.
558 .RE
559
560 .SH CONTEXT
561 Constructors can be invoked during any call to \fBkmem_cache_alloc()\fR, and
562 will run in that context. Similarly, destructors can be invoked during any call
563 to \fBkmem_cache_free()\fR, and can also be invoked during
564 \fBkmem_cache_destroy()\fR. Therefore, the functions that a constructor or
565 destructor invokes must be appropriate in that context. Furthermore, the
566 allocator may also call the constructor and destructor on objects still under
567 its control without client involvement.
568 .sp
569 .LP
570 \fBkmem_cache_create()\fR and \fBkmem_cache_destroy()\fR must not be called
571 from interrupt context. \fBkmem_cache_create()\fR can also block for available
572 memory.
573 .sp
574 .LP
575 \fBkmem_cache_alloc()\fR can be called from interrupt context only if the
576 \fBKM_NOSLEEP\fR flag is set. It can be called from user or kernel context with
577 any valid flag.
578 .sp
579 .LP
580 \fBkmem_cache_free()\fR can be called from user, kernel, or interrupt context.
581 .sp
582 .LP
583 \fBkmem_cache_set_move()\fR is called from the same context as
584 \fBkmem_cache_create()\fR, immediately after \fBkmem_cache_create()\fR and
585 before allocating any objects from the cache.
586 .sp
587 .LP
588 The registered \fBmove()\fR callback is always invoked in the same global
589 callback thread dedicated for move requests, guaranteeing that no matter how
590 many clients register a \fBmove()\fR function, the allocator never tries to
591 move more than one object at a time. Neither the allocator nor the client can
592 be assumed to know the object's whereabouts at the time of the callback.
593 .SH EXAMPLES
594 \fBExample 1 \fRObject Caching
595 .sp
596 .LP
597 Consider the following data structure:
692 This makes \fBfoo\fR allocation fast, because the allocator will usually do
693 nothing more than fetch an already-constructed \fBfoo\fR from the cache.
694 \fBfoo_constructor\fR and \fBfoo_destructor\fR will be invoked only to populate
695 and drain the cache, respectively.
696
697 .LP
698 \fBExample 2 \fRRegistering a Move Callback
699 .sp
700 .LP
701 To register a \fBmove()\fR callback:
702
703 .sp
704 .in +2
705 .nf
706 object_cache = kmem_cache_create(...);
707 kmem_cache_set_move(object_cache, object_move);
708 .fi
709 .in -2
710
711 .SH RETURN VALUES
712 If successful, the constructor function must return \fB0\fR. If KM_NOSLEEP is
713 set and memory cannot be allocated without sleeping, the constructor must
714 return -\fB1\fR.
715 .sp
716 .LP
717 \fBkmem_cache_create()\fR returns a pointer to the allocated cache.
718 .sp
719 .LP
720 If successful, \fBkmem_cache_alloc()\fR returns a pointer to the allocated
721 object. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated without
722 sleeping, \fBkmem_cache_alloc()\fR returns \fBNULL\fR.
723 .SH ATTRIBUTES
724 See \fBattributes\fR(5) for descriptions of the following attributes:
725 .sp
726
727 .sp
728 .TS
729 box;
730 c | c
731 l | l .
732 ATTRIBUTE TYPE ATTRIBUTE VALUE
733 _
734 Interface Stability Committed
|
1 '\" te
2 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright 2022 Joyent, Inc.
4 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH KMEM_CACHE_CREATE 9F "Feb 18, 2015"
9 .SH NAME
10 kmem_cache_create, kmem_cache_alloc, kmem_cache_free, kmem_cache_destroy,
11 kmem_cache_set_move \- kernel memory cache allocator operations
12 .SH SYNOPSIS
13 .nf
14 #include <sys/types.h>
15 #include <sys/kmem.h>
16
17 \fBkmem_cache_t *\fR\fBkmem_cache_create\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fIbufsize\fR,
18 \fBsize_t\fR \fIalign\fR, \fBint\fR (*\fIconstructor\fR)(void *, void *, int),
19 \fBvoid\fR (*\fIdestructor\fR)(void *, void *), \fBvoid\fR (*\fIreclaim\fR)(void *),
20 \fBvoid\fR *\fIprivate\fR, \fBvoid\fR *\fIvmp\fR, \fBint\fR \fIcflags\fR);
21 .fi
22
23 .LP
153 .na
154 \fB\fIkmflag\fR\fR
155 .ad
156 .RS 15n
157 Possible flags are:
158 .sp
159 .ne 2
160 .na
161 \fB\fBKM_SLEEP\fR\fR
162 .ad
163 .RS 15n
164 Allow sleeping (blocking) until memory is available.
165 .RE
166
167 .sp
168 .ne 2
169 .na
170 \fB\fBKM_NOSLEEP\fR\fR
171 .ad
172 .RS 15n
173 Return NULL immediately if memory is not available, but after an aggressive
174 reclaiming attempt. Any mention of \fBKM_NOSLEEP\fR without mentioning
175 \fBKM_NOSLEEP_LAZY\fR (see below) applies to both values.
176 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB\fBKM_NOSLEEP_LAZY\fR\fR
182 .ad
183 .RS 15n
184 Return NULL immediately if memory is not available, without the aggressive
185 reclaiming attempt. This is actually two flags combined:
186 (\fBKM_NOSLEEP\fR | \fBKM_NORMALPRI\fR), the latter flag indicating not to
187 attempt reclamation before giving up and returning NULL.
188 .RE
189
190 .sp
191 .ne 2
192 .na
193 \fB\fBKM_PUSHPAGE\fR\fR
194 .ad
195 .RS 15n
196 Allow the allocation to use reserved memory.
197 .RE
198
199 .RE
200
201 .sp
202 .ne 2
203 .na
204 \fB\fIobj\fR\fR
205 .ad
206 .RS 15n
207 Pointer to the object allocated by \fBkmem_cache_alloc()\fR.
208 .RE
209
210 .sp
211 .ne 2
212 .na
348 A driver should call \fBkmem_cache_create()\fR at the time of \fB_init\fR(9E)
349 or \fBattach\fR(9E), and call the corresponding \fBkmem_cache_destroy()\fR at
350 the time of \fB_fini\fR(9E) or \fBdetach\fR(9E).
351 .sp
352 .LP
353 \fBkmem_cache_create()\fR creates a cache of objects, each of size
354 \fIbufsize\fR bytes, aligned on an \fIalign\fR boundary. Drivers not requiring
355 a specific alignment can pass 0. \fIname\fR identifies the cache for statistics
356 and debugging. \fIconstructor\fR and \fIdestructor\fR convert plain memory into
357 objects and back again; \fIconstructor\fR can fail if it needs to allocate
358 memory but cannot. \fIprivate\fR is a parameter passed to the constructor and
359 destructor callbacks to support parameterized caches (for example, a pointer to
360 an instance of the driver's soft-state structure). To facilitate debugging,
361 \fBkmem_cache_create()\fR creates a \fBkstat\fR(9S) structure of class
362 \fBkmem_cache\fR and name \fIname\fR. It returns an opaque pointer to the
363 object cache.
364 .sp
365 .LP
366 \fBkmem_cache_alloc()\fR gets an object from the cache. The object will be in
367 its constructed state. \fIkmflag\fR has either \fBKM_SLEEP\fR or
368 \fBKM_NOSLEEP\fR set, indicating whether it is acceptable to wait for memory
369 if none is currently available.
370 .sp
371 .LP
372 A small pool of reserved memory is available to allow the system to progress
373 toward the goal of freeing additional memory while in a low memory situation.
374 The \fBKM_PUSHPAGE\fR flag enables use of this reserved memory pool on an
375 allocation. This flag can be used by drivers that implement \fBstrategy\fR(9E)
376 on memory allocations associated with a single I/O operation. The driver
377 guarantees that the I/O operation will complete (or timeout) and, on
378 completion, that the memory will be returned. The \fBKM_PUSHPAGE\fR flag should
379 be used only in \fBkmem_cache_alloc()\fR calls. All allocations from a given
380 cache should be consistent in their use of the flag. A driver that adheres to
381 these restrictions can guarantee progress in a low memory situation without
382 resorting to complex private allocation and queuing schemes. If
383 \fBKM_PUSHPAGE\fR is specified, \fBKM_SLEEP\fR can also be used without causing
384 deadlock.
385 .sp
386 .LP
387 \fBkmem_cache_free()\fR returns an object to the cache. The object must be in
388 its constructed state.
389 .sp
571 Pointer to the object that has become movable since an earlier refusal to move
572 it.
573 .RE
574
575 .SH CONTEXT
576 Constructors can be invoked during any call to \fBkmem_cache_alloc()\fR, and
577 will run in that context. Similarly, destructors can be invoked during any call
578 to \fBkmem_cache_free()\fR, and can also be invoked during
579 \fBkmem_cache_destroy()\fR. Therefore, the functions that a constructor or
580 destructor invokes must be appropriate in that context. Furthermore, the
581 allocator may also call the constructor and destructor on objects still under
582 its control without client involvement.
583 .sp
584 .LP
585 \fBkmem_cache_create()\fR and \fBkmem_cache_destroy()\fR must not be called
586 from interrupt context. \fBkmem_cache_create()\fR can also block for available
587 memory.
588 .sp
589 .LP
590 \fBkmem_cache_alloc()\fR can be called from interrupt context only if the
591 \fBKM_NOSLEEP\fR flag is set. It can be called from user or kernel context
592 with any valid flag.
593 .sp
594 .LP
595 \fBkmem_cache_free()\fR can be called from user, kernel, or interrupt context.
596 .sp
597 .LP
598 \fBkmem_cache_set_move()\fR is called from the same context as
599 \fBkmem_cache_create()\fR, immediately after \fBkmem_cache_create()\fR and
600 before allocating any objects from the cache.
601 .sp
602 .LP
603 The registered \fBmove()\fR callback is always invoked in the same global
604 callback thread dedicated for move requests, guaranteeing that no matter how
605 many clients register a \fBmove()\fR function, the allocator never tries to
606 move more than one object at a time. Neither the allocator nor the client can
607 be assumed to know the object's whereabouts at the time of the callback.
608 .SH EXAMPLES
609 \fBExample 1 \fRObject Caching
610 .sp
611 .LP
612 Consider the following data structure:
707 This makes \fBfoo\fR allocation fast, because the allocator will usually do
708 nothing more than fetch an already-constructed \fBfoo\fR from the cache.
709 \fBfoo_constructor\fR and \fBfoo_destructor\fR will be invoked only to populate
710 and drain the cache, respectively.
711
712 .LP
713 \fBExample 2 \fRRegistering a Move Callback
714 .sp
715 .LP
716 To register a \fBmove()\fR callback:
717
718 .sp
719 .in +2
720 .nf
721 object_cache = kmem_cache_create(...);
722 kmem_cache_set_move(object_cache, object_move);
723 .fi
724 .in -2
725
726 .SH RETURN VALUES
727 If successful, the constructor function must return \fB0\fR. If
728 \fBKM_NOSLEEP\fR or \fBKM_NOSLEEP_LAZY\fR is set and memory cannot be
729 allocated without sleeping, the constructor must return -\fB1\fR. If the
730 constructor takes extraordinary steps during a \fBKM_NOSLEEP\fR construction,
731 it may not take those for a \fBKM_NOSLEEP_LAZY\fR construction.
732 .sp
733 .LP
734 \fBkmem_cache_create()\fR returns a pointer to the allocated cache.
735 .sp
736 .LP
737 If successful, \fBkmem_cache_alloc()\fR returns a pointer to the allocated
738 object. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated without
739 sleeping, \fBkmem_cache_alloc()\fR returns \fBNULL\fR.
740 .SH ATTRIBUTES
741 See \fBattributes\fR(5) for descriptions of the following attributes:
742 .sp
743
744 .sp
745 .TS
746 box;
747 c | c
748 l | l .
749 ATTRIBUTE TYPE ATTRIBUTE VALUE
750 _
751 Interface Stability Committed
|