msp_objcache.h File Reference

Functions to support object cache memory allocation for the MultiServices PIC SDK. More...


Data Structures

struct  msp_shm_params_s
 Parameters passed to SHM initialization functions. More...
struct  msp_shm_stats_s
 Statistics for SHM. More...
struct  msp_oc_params_s
 Parameters passed to OBJCACHE initialization functions. More...
struct  msp_oc_info_s
 Information retrieved for an object cache. More...

Constants used in allocators parameters.

#define SHM_NAME_LEN   32
 Shared memory allocator name length.
#define OC_NAME_LEN   32
 Object cache allocator name length.
#define MSP_OC_HANDLE_INVALID   NULL
 Invalid object cache handle.
#define APP_NAME_LEN   32

Defines

#define MSP_APP_SHM_RESTART   0x1
 shm_flags to enable the application restart.

Typedefs

typedef void * msp_shm_handle_t
 Shared memory allocator handle.
typedef void * msp_shm_iterator_ctxt_t
 Shared memory iterator context.
typedef void * msp_objcache_iterator_ctxt_t
 Object cache iterator context.
typedef msp_shm_params_s msp_shm_params_t
 Parameters passed to SHM initialization functions.
typedef msp_shm_stats_s msp_shm_stats_t
 Statistics for SHM.
typedef void * msp_oc_handle_t
 Object cache allocator handle.
typedef msp_oc_params_s msp_objcache_params_t
 Parameters passed to OBJCACHE initialization functions.
typedef msp_oc_info_s msp_objcache_info_t
 Information retrieved for an object cache.

Functions

int msp_shm_allocator_init (msp_shm_params_t *shm_params)
 Initializes the SHM allocator for the MultiServices PIC.
int msp_shm_allocator_attach (msp_shm_params_t *shm_params)
 Attaches to an existing SHM allocator.
int msp_shm_allocator_detach (msp_shm_params_t *shm_params)
 Destroys shm context, allocated by msp_shm_allocator_attach.
void * msp_shm_alloc (msp_shm_handle_t shm, size_t sz)
 Allocates memory from an SHM.
void msp_shm_free (msp_shm_handle_t shm, void *addr)
 Frees memory to the SHM.
int msp_shm_stats (msp_shm_handle_t shm, msp_shm_stats_t *stats)
 Gets statistics for SHM.
int msp_shm_is_red_zone (msp_shm_handle_t shmh)
 check to see whether we are in red zone
int msp_objcache_create (msp_objcache_params_t *oc_params)
 Creates an object cache with the parameters specified.
int msp_objcache_attach (msp_objcache_params_t *oc_params)
 Attaches to an object cache created by msp_objcache_create.
void * msp_objcache_alloc (msp_oc_handle_t oc, int cpuid, int client_id)
 Allocates memory from OBJCACHE.
int msp_objcache_free (msp_oc_handle_t oc, void *mem, int cpuid, int client_id)
 Free memory to OBJCACHE.
int msp_objcache_destroy (msp_oc_handle_t oc)
 Destroys an object cache.
int msp_objcache_reclaim (msp_shm_handle_t shm)
 Reclaims memory stuck in object caches and returns them to SHM.
int msp_objcache_info (msp_shm_handle_t shm, msp_objcache_info_t *info)
 Retrieves information for an object cache.
void * msp_shm_alloc_app_sm (msp_shm_handle_t shm, size_t sz, const char *app_name)
 Add application context for this SHM.
void msp_shm_free_app_sm (msp_shm_handle_t shm, const char *app_name)
 Frees application context for this SHM.
void * msp_shm_get_app_sm (const char *shm_name, const char *app_name)
 Retrieve already allocated application context for this SHM.
int msp_shm_detach_obj_cache (void)
 Removes shared memory address mappings from a process context.
int msp_shm_get_next (msp_shm_iterator_ctxt_t *ctxt, char *shm_name)
 Iterator to get all the allocated SHM.
int msp_objcache_get_next (msp_shm_handle_t shm, void **ctxt, char *oc_name)
 Iterator to get all the allocated object cache of a SHM.


Detailed Description

Functions to support object cache memory allocation for the MultiServices PIC SDK.

This file provides the functions to support a userspace allocator on top of the large TLB mapping created for a MultiServices PIC using the CLI:


Function Documentation

void* msp_objcache_alloc msp_oc_handle_t  oc,
int  cpuid,
int  client_id
 

Allocates memory from OBJCACHE.

Parameters:
[in] oc Handle to OBJCACHE. The size is not passed as OBJCACHE is a fixed size allocator.
[in] cpuid CPU id to which the current thread or process is bound.
[in] client_id Customer id associated with the allocated object. Use service set ID when using plugin architecture, and use zero otherwise.
Returns:
Pointer to allocated memory on success; otherwise NULL.

int msp_objcache_attach msp_objcache_params_t oc_params  ) 
 

Attaches to an object cache created by msp_objcache_create.

Parameters:
[in,out] oc_params OBJCACHE parameters, OC handle is returned in params ('oc'). oc_name is used as key to attach. oc_shm is the shm handle passed to msp_objcache_create
Returns:
MSP_OK on success; otherwise, return one of the error codes listed below:
  • MSP_INVALID_ARG - One of the passed parameters is invalid.
  • MSP_OC_ATTACH_FAIL - Could not attach to object cache, a syslog is generated to identify the error.

int msp_objcache_create msp_objcache_params_t oc_params  ) 
 

Creates an object cache with the parameters specified.

This function should only be called by the master process or thread. Restart is not supported. Multiple object caches with different names can be created.

Parameters:
[in,out] oc_params OBJCACHE parameters, OC handle is returned in params ('oc').
Returns:
MSP_OK on success; otherwise, returns one of the error codes listed below:
  • MSP_INVALID_ARG - One of the passed parameters is invalid.
  • MSP_SHM_ENOMEM - Failed to create object cache, SHM out of memory.
  • MSP_OC_INIT_FAIL - Could not create object cache, a syslog is generated to identify the error.

int msp_objcache_destroy msp_oc_handle_t  oc  ) 
 

Destroys an object cache.

This is a place holder to support restarts in the future.

int msp_objcache_free msp_oc_handle_t  oc,
void *  mem,
int  cpuid,
int  client_id
 

Free memory to OBJCACHE.

Parameters:
[in] oc Handle to OBJCACHE.
[in] mem Memory to be freed.
[in] cpuid CPU id to which the current thread or process is bound.
[in] client_id Customer id associated with the freed object. Use service set ID when using plugin architecture, and use zero otherwise.
Returns:
MSP_OK on success; otherwise an error code:
  • MSP_INVALID_ARG - Arguments passed are invalid.

int msp_objcache_get_next msp_shm_handle_t  shm,
void **  ctxt,
char *  oc_name
 

Iterator to get all the allocated object cache of a SHM.

Parameters:
[in] shm SHM handle
[in,out] *ctxt Context maintained by iterator. ctxt must point to a NULL value to start the iterator.
[out] *oc_name Name of the object cache. This buffer should be atleast OC_NAME_LEN long.
Returns:
MSP_OK when a valid object cache name is returned; MSP_SHM_NONE to indicate end of iteration. In case of error following error codes are returned:
  • MSP_INVALID_ARG - Arguments passed are invalid.

int msp_objcache_info msp_shm_handle_t  shm,
msp_objcache_info_t info
 

Retrieves information for an object cache.

This function provides a way to look up object cache parameters and retrieve statistics given the name or object cache handle of an object cache. If the object cache handle is valid, it's used before doing a name-based lookup. To ensure lookup via the object cache name, the object cache handle must be set to MSP_OC_HANDLE_INVALID in info.

Parameters:
[in] shm SHM handle
[in,out] info oc or name needs to be passed to the function. All other fields in info are populated by the function.
Returns:
MSP_OK on success; otherwise an error code:
  • MSP_INVALID_ARG - Arguments passed are invalid.
  • MSP_OC_INFO_FAIL - Unable to find object cache.

int msp_objcache_reclaim msp_shm_handle_t  shm  ) 
 

Reclaims memory stuck in object caches and returns them to SHM.

This function is needed to make sure that SHM memory is efficiently shared between different object caches. This should only be called periodically in the data loops by one thread designated as master. This function only tries to reclaim if the free memory in SHM falls to less than 25% of total SHM memory.

Parameters:
[in] shm SHM handle

void* msp_shm_alloc msp_shm_handle_t  shm,
size_t  sz
 

Allocates memory from an SHM.

Parameters:
[in] shm Handle to SHM allocator.
[in] sz Size of memory to be allocated.
Returns:
Pointer to allocated memory on success; otherwise NULL.

void* msp_shm_alloc_app_sm msp_shm_handle_t  shm,
size_t  sz,
const char *  app_name
 

Add application context for this SHM.

This function is used to add an application context for this SHM. Application context is an area allocated within the SHM and identifiable by a given name.

Parameters:
[in] shm SHM handle.
[in] sz Size of application context.
[in] app_name Name to identify the application context.
Returns:
Pointer to application context in case of success; otherwise NULL.

int msp_shm_allocator_attach msp_shm_params_t shm_params  ) 
 

Attaches to an existing SHM allocator.

This function can only be called after the initialization is done by a master process. If multiple threads are spawned within the same process, attach is not required. This is only needed when SHM is used across multiple processes.

Parameters:
[in,out] shm_params SHM parameters, shm handle is returned in the params ('shm'). Name in shm-params is used to attach to the SHM. The name used must match the name used in msp_shm_allocator_init.
Returns:
MSP_OK on success; otherwise, return the error codes listed below:
  • MSP_SHM_ATTACH_FAIL - Could not attach to the SHM, a syslog is generated to identify the error.

int msp_shm_allocator_detach msp_shm_params_t shm_params  ) 
 

Destroys shm context, allocated by msp_shm_allocator_attach.

Parameters:
[in] shm_params SHM handle field should be a valid handle.
Returns:
MSP_OK on success; otherwise, return the error codes listed below:
  • MSP_INVALID_ARG - One of the passed parameters is invalid.

int msp_shm_allocator_init msp_shm_params_t shm_params  ) 
 

Initializes the SHM allocator for the MultiServices PIC.

This function should only be called by the master processor thread. Restart is not supported. Only one instance of SHM is supported for a PIC.

Parameters:
[in,out] shm_params SHM parameters, shm handle is returned in the the params ('shm'). If the size in shm-params is set to "0", then the complete shm is assigned. Subsequenet requests for shm creation will fail
Returns:
MSP_OK on success; otherwise, returns the error code listed below:
  • MSP_SHM_INIT_FAIL - Could not initialize the shm, a syslog is generated to identify the error.

int msp_shm_detach_obj_cache void   ) 
 

Removes shared memory address mappings from a process context.

This API disables the process's access to all shared memory.

Returns:
MSP_OK on success; otherwise MSP_ERROR.

void msp_shm_free msp_shm_handle_t  shm,
void *  addr
 

Frees memory to the SHM.

Parameters:
[in] shm Handle to the SHM allocator.
[in] addr Memory to be freed.

void msp_shm_free_app_sm msp_shm_handle_t  shm,
const char *  app_name
 

Frees application context for this SHM.

This function is used to free an application context for this SHM.

Parameters:
[in] shm shm handle
[in] app_name Name to identify the application context.

void* msp_shm_get_app_sm const char *  shm_name,
const char *  app_name
 

Retrieve already allocated application context for this SHM.

This function is used to retrieve already allocated application context for this SHM.

NOTE: Before calling this API the shared memory addresses must be mapped to process context.

Parameters:
[in] shm SHM handle
[in] app_name Name to identify the application context.
Returns:
Pointer to application context in case of success; otherwise NULL.

int msp_shm_get_next msp_shm_iterator_ctxt_t ctxt,
char *  shm_name
 

Iterator to get all the allocated SHM.

Parameters:
[in,out] *ctxt Context maintained by iterator. ctxt must point to a NULL value to start the iterator.
[out] *shm_name Name of the Shared memory. This buffer should be atleast SHM_NAME_LEN long.
Returns:
MSP_OK when a valid shared memory name is returned; MSP_SHM_NONE to indicate end of iteration. In case of error following error codes are returned:
  • MSP_INVALID_ARG - Arguments passed are invalid.
  • MSP_ERROR - System error occured.

int msp_shm_is_red_zone msp_shm_handle_t  shmh  ) 
 

check to see whether we are in red zone

Parameters:
[in] shm Handle to SHM allocator.

int msp_shm_stats msp_shm_handle_t  shm,
msp_shm_stats_t stats
 

Gets statistics for SHM.

Parameters:
[in] shm Handle to SHM allocator.
[out] *stats stats retrieved from shm.
Returns:
MSP_OK on success. MSP_INVALID_ARG on failure.


2007-2009 Juniper Networks, Inc. All rights reserved. The information contained herein is confidential information of Juniper Networks, Inc., and may not be used, disclosed, distributed, modified, or copied without the prior written consent of Juniper Networks, Inc. in an express license. This information is subject to change by Juniper Networks, Inc. Juniper Networks, the Juniper Networks logo, and JUNOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
Generated on Sun May 30 20:24:47 2010 for libmp-sdk by Doxygen 1.4.5