diff options
Diffstat (limited to 'inc/HAP_pls.h')
-rw-r--r-- | inc/HAP_pls.h | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/inc/HAP_pls.h b/inc/HAP_pls.h new file mode 100644 index 0000000..23d7ddd --- /dev/null +++ b/inc/HAP_pls.h @@ -0,0 +1,129 @@ +#ifndef HAP_PLS_H +#define HAP_PLS_H + +/** + * Copyright (c) 2019, The Linux Foundation. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * * Neither the name of The Linux Foundation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS + * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN + * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <stdint.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Process local storage is local storage for the hlos process context. + * + * Warning, this API should only be called from within a thread started by FastRPC, and not from + * any user created threads via the qurt apis. + * + * When used from within a FastRPC started thread this will attach + * desturctors to the lifetime of the HLOS process that is making the + * rpc calls. Users can use this to store context for the lifetime of + * the calling process on the hlos. + * + * Recovering instances + * -------------------- + * + * To maintain the same instance structure for a caller from the HLOS users + * can use the HAP_pls_add_lookup api, which will lookup the key, and add it + * if its not already present. + * For example: + * + * static int my_instance(struct my_struct* me) { + * return HAP_pls_add_lookup((uintptr_t)my_ctor, //type, some unique static address + * 0, //key, for different type instances + * sizeof(*me), //size of our struture + * my_ctor, //structure ctor + * 0, //aditional user context for ctor + * my_dtor, //desturctor + * &me); //result + * } + * + * First call to my_instance will initialize the structure by allocating it and calling my_ctor. + * Second call to my_instance will return the created instance. + * This API is thread safe, but when two threads try to intialize the structure the first + * time they may both create an instance, but only 1 will be returned. + * The destructor will be called when the HLOS process exits. + * + * See HAP_pls_add and HAP_pls_add_lookup. + * + * Exit Hooks + * ---------- + * + * Users can use either HAP_pls_add_lookup or HAP_pls_add to add a destructor that will be + * called when the HLOS process exits. The main difference between the two functions is that + * HAP_pls_add will always add, and the last instance added will be the one returned by + * HAP_pls_lookup. + * + * + */ + +/** + * adds a new type/key to the local storage, overriding + * any previous value at the key. Overriding the key + * does not cause the destructor to run. Destructors are + * run when the HLOS process exits. + * + * @param type, type part of the key to be used for lookup, + * these should be static addresses, like the address of a function. + * @param key, the key to be used for lookup + * @param size, the size of the data + * @param ctor, constructor that takes a context and memory of size + * @param ctx, constructor context passed as the first argument to ctor + * @param dtor, destructor to run at pls shutdown + * @param ppo, output data + * @retval, 0 for success + */ +int HAP_pls_add(uintptr_t type, uintptr_t key, int size, int (*ctor)(void* ctx, void* data), void* ctx, void (*dtor)(void*), void** ppo); + +/** + * Like add, but will only add 1 item, and return the same item on the + * next add. If two threads try to call this function at teh same time + * they will both receive the same value as a result, but the constructors + * may be called twice. + * item if its already there, otherwise tries to add. + * ctor may be called twice + * callers should avoid calling pls_add for the same type/key which will override the singleton + */ +int HAP_pls_add_lookup(uintptr_t type, uintptr_t key, int size, int (*ctor)(void* ctx, void* data), void* ctx, void (*dtor)(void*), void** ppo); + +/** + * finds the last data pointer added for key to the local storage + * + * @param key, the key to be used for lookup + * @param ppo, output data + * @retval, 0 for success + */ +int HAP_pls_lookup(uintptr_t type, uintptr_t key, void** ppo); + + +#ifdef __cplusplus +} +#endif +#endif //HAP_PLS_H |