Annotation of libaitsess/inc/aitsess.h, revision 1.4.2.4

1.2       misho       1: /*************************************************************************
                      2: * (C) 2008 AITNET ltd - Sofia/Bulgaria - <misho@aitbg.com>
                      3: *  by Michael Pounov <misho@openbsd-bg.org>
                      4: *
                      5: * $Author: misho $
1.4.2.4 ! misho       6: * $Id: aitsess.h,v 1.4.2.3 2012/02/27 23:57:12 misho Exp $
1.2       misho       7: *
1.3       misho       8: **************************************************************************
                      9: The ELWIX and AITNET software is distributed under the following
                     10: terms:
                     11: 
                     12: All of the documentation and software included in the ELWIX and AITNET
                     13: Releases is copyrighted by ELWIX - Sofia/Bulgaria <info@elwix.org>
                     14: 
1.4.2.3   misho      15: Copyright 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
1.3       misho      16:        by Michael Pounov <misho@elwix.org>.  All rights reserved.
                     17: 
                     18: Redistribution and use in source and binary forms, with or without
                     19: modification, are permitted provided that the following conditions
                     20: are met:
                     21: 1. Redistributions of source code must retain the above copyright
                     22:    notice, this list of conditions and the following disclaimer.
                     23: 2. Redistributions in binary form must reproduce the above copyright
                     24:    notice, this list of conditions and the following disclaimer in the
                     25:    documentation and/or other materials provided with the distribution.
                     26: 3. All advertising materials mentioning features or use of this software
                     27:    must display the following acknowledgement:
                     28: This product includes software developed by Michael Pounov <misho@elwix.org>
                     29: ELWIX - Embedded LightWeight unIX and its contributors.
                     30: 4. Neither the name of AITNET nor the names of its contributors
                     31:    may be used to endorse or promote products derived from this software
                     32:    without specific prior written permission.
                     33: 
                     34: THIS SOFTWARE IS PROVIDED BY AITNET AND CONTRIBUTORS ``AS IS'' AND
                     35: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     36: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     37: ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     38: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     39: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     40: OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     41: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     42: LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     43: OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     44: SUCH DAMAGE.
                     45: */
1.1       misho      46: #ifndef __AITSESS_H
                     47: #define __AITSESS_H
                     48: 
                     49: 
1.4.2.2   misho      50: #include <pthread.h>
1.3       misho      51: #include <assert.h>
1.1       misho      52: #include <semaphore.h>
1.4       misho      53: #include <aitio.h>
1.1       misho      54: 
1.4       misho      55: #define SHARED_UNKNOWN -1
                     56: #define SHARED_IPC     0
                     57: #define SHARED_MAP     1
1.1       misho      58: 
                     59: #define IS_VAL         0x0
                     60: #define IS_ADD         0x40000000
                     61: #define IS_DEF         0x80000000
                     62: 
                     63: #define ISNEW(x)       (((x) & IS_ADD) == IS_ADD)
                     64: #define ISDEF(x)       (((x) & IS_DEF) == IS_DEF)
                     65: 
1.4       misho      66: #define MAX_ATTRIBUTE  64
1.1       misho      67: #define MAX_SEMNAME    14
                     68: 
1.4.2.1   misho      69: /* Memory pool */
                     70: 
                     71: #define MEM_BUCKETS    28      /* 32 bits - 4 bits = 28 items in bucket array */
                     72: 
                     73: struct tagAlloc {
                     74:        char                    alloc_name[MAX_ATTRIBUTE];
                     75:        volatile unsigned int   alloc_flags;
                     76: 
                     77:        unsigned int            *alloc_mem;
                     78: 
                     79:        TAILQ_ENTRY(tagAlloc)   alloc_node;
                     80: };
                     81: typedef TAILQ_HEAD(, tagAlloc) mpool_bucket_t;
                     82: 
                     83: typedef struct _tagMPool {
                     84:        pthread_mutex_t pool_mtx;
                     85: 
                     86:        struct {
                     87:                unsigned long alloc;
                     88:                unsigned long free;
                     89:                unsigned long cache;
                     90:        } pool_calls;
                     91:        struct {
                     92:                unsigned long alloc;
                     93:                unsigned long free;
                     94:                unsigned long cache;
                     95:        } pool_bytes;
                     96:        struct {
                     97:                unsigned long max;
                     98:                unsigned long curr;
                     99:        } pool_quota;
                    100: 
                    101:        /* pool buckets */
                    102:        mpool_bucket_t  pool_active[MEM_BUCKETS];
                    103:        mpool_bucket_t  pool_inactive[MEM_BUCKETS];
                    104: } mpool_t;
                    105: #define mpool_lock(x)  (assert((x)), pthread_mutex_lock(&(x)->pool_mtx))
                    106: #define mpool_unlock(x)        (assert((x)), pthread_mutex_unlock(&(x)->pool_mtx))
                    107: 
                    108: /* Shared memory session */
1.1       misho     109: 
1.4       misho     110: typedef struct tagSess {
1.1       misho     111:        key_t   key;
1.4       misho     112:        char    type;
                    113:        char    zcpy;
                    114: 
                    115:        char    name[BUFSIZ];
1.1       misho     116:        off_t   eom;
                    117:        void    *addr;
                    118:        off_t   offset;
                    119:        union {
                    120:                int     shmid;
                    121:                int     fd;
                    122:        } mem;
                    123:        union {
                    124:                int     semid;
                    125:                sem_t   *sid;
                    126:        } id;
1.4       misho     127: 
                    128:        struct {
                    129:                int (*create)(int, long, void *, ...);
                    130:                void (*destroy)(void *);
                    131:                void *(*attach)(void *, void *);
                    132:                void (*detach)(void *);
                    133:                void (*notSem)(void *);
                    134:                int (*isSemOK)(void *);
                    135:                int (*incSem)(void *);
                    136:                int (*decSem)(void *);
                    137:        } sess;
                    138: } ait_sess_t;
1.1       misho     139: 
                    140: 
                    141: // -------------------------------------------------------
                    142: // sess_GetErrno() Get error code of last operation
                    143: inline int sess_GetErrno();
                    144: // sess_GetError() Get error text of last operation
                    145: inline const char *sess_GetError();
1.4       misho     146: // sess_SetErr() Set error to variables for internal use!!!
                    147: inline void sess_SetErr(int eno, char *estr, ...);
1.1       misho     148: // -------------------------------------------------------
                    149: 
                    150: 
                    151: /*
1.4.2.1   misho     152:  * mpool_init() - Init memory pool
                    153:  *
                    154:  * return: =NULL error or !=NULL new allocated pool
                    155:  */
                    156: mpool_t *mpool_init(void);
                    157: /*
                    158:  * mpool_destroy() - Destroy memory pool
                    159:  *
                    160:  * @mp = Memory pool
                    161:  * return: none
                    162:  */
                    163: void mpool_destroy(mpool_t ** __restrict mp);
                    164: /*
1.4.2.3   misho     165:  * mpool_purge() - Purge memory block cache and release resources
                    166:  *
                    167:  * @mp = Memory pool
                    168:  * @atmost = Free at most in buckets
                    169:  * return: -1 error or 0 ok
                    170:  */
1.4.2.4 ! misho     171: int mpool_purge(mpool_t * __restrict mp, unsigned int atmost);
1.4.2.3   misho     172: /*
1.4.2.1   misho     173:  * mpool_malloc() - Memory allocation
                    174:  *
                    175:  * @mp = Memory pool
                    176:  * @size = Size
                    177:  * @memname = Optional memory block name
                    178:  * return: NULL error or !=NULL ok allocated memory
                    179:  */
                    180: void *mpool_malloc(mpool_t * __restrict mp, unsigned int size, const char *memname);
                    181: /*
                    182:  * mpool_free() Free allocated memory with mpool_alloc()
                    183:  *
                    184:  * @mp = Memory pool
                    185:  * @data = Allocated memory data
                    186:  * @purge = if !=0 force release memory block
                    187:  * return: <0 error or 0 ok released memory block
                    188:  */
                    189: int mpool_free(mpool_t * __restrict mp, void * __restrict data, int purge);
                    190: /*
                    191:  * mpool_free2() Free allocated memory with mpool_alloc() by size and memory name
                    192:  *
                    193:  * @mp = Memory pool
                    194:  * @size = Allocated memory data size
                    195:  * @memname = Memory name
                    196:  * @purge = if !=0 force release memory block
                    197:  * return: <0 error or 0 ok released memory block
                    198:  */
1.4.2.2   misho     199: int mpool_free2(mpool_t * __restrict mp, unsigned int size, const char *memname, int purge);
1.4.2.1   misho     200: /*
                    201:  * mpool_getmembynam() Find allocated memory block by size and memory name
                    202:  *
                    203:  * @mp = Memory pool
                    204:  * @size = Memory size
                    205:  * @memname = Memory name
                    206:  * return: NULL error or not found and !=NULL allocated memory 
                    207:  */
1.4.2.2   misho     208: inline struct tagAlloc *mpool_getmembynam(mpool_t * __restrict mp, unsigned int size, const char *memname);
1.4.2.3   misho     209: /*
                    210:  * mpool_getsizebyaddr() - Get size of allocated memory block by address
                    211:  *
                    212:  * @data = allocated memory from mpool_malloc()
                    213:  * return: usable size of allocated memory block
                    214:  */
                    215: inline unsigned int mpool_getsizebyaddr(void * __restrict data);
                    216: /*
                    217:  * mpool_chkaddr() - Check validity of given address
                    218:  *
                    219:  * @data = allocated memory from mpool_malloc()
                    220:  * return: -1 bad address, 1 corrupted address or 0 ok
                    221:  */
                    222: inline int mpool_chkaddr(void * __restrict data);
1.4.2.1   misho     223: 
                    224: 
                    225: /*
1.4       misho     226:  * sess_initSession() Initializing session structure, if session file not exists creating with specified tech
                    227:  *
                    228:  * @id = Technology using in session. SHARED_IPC IPC tech orSHARED_MAP BSD MemoryMap tech
1.1       misho     229:  * @csFName = Session filename for build key and identified
1.3       misho     230:  * @Sess = Session item, if =NULL allocate memory for session after use must be free!
1.1       misho     231:  * return: 0 OK new key created, -1 error: no memory or file not created, 1 OK key finded
1.4       misho     232:  */
                    233: int sess_initSession(int id, const char *csFName, ait_sess_t ** __restrict Sess);
1.1       misho     234: /*
1.4       misho     235:  * sess_freeSession() Free allocated memory for session item and delete session file if present name
                    236:  *
1.1       misho     237:  * @Sess = Session item
1.4       misho     238:  * return: none
                    239:  */
                    240: void sess_freeSession(ait_sess_t ** __restrict Sess);
                    241: 
1.1       misho     242: 
                    243: /*
                    244:  * map_createSession() MMAP Created session and allocated resources
1.4       misho     245:  *
                    246:  * @nSeed = Seed for securing key, if =-1 must add ready for use key
                    247:  * @nSize = Allocated shared memory size in bytes
1.1       misho     248:  * @Sess = Session item
1.4       misho     249:  * @... = If nSeed == -1 add ready for use key value
1.1       misho     250:  * return: 0 Ok successful, -1 error: not allocated resources
1.4       misho     251:  */
                    252: int map_createSession(int nSeed, long nSize, ait_sess_t * __restrict Sess, ...);
1.1       misho     253: /*
                    254:  * map_destroySession() MMAP free shared resources
1.4       misho     255:  *
1.1       misho     256:  * @Sess = Session item
1.4       misho     257:  * return: none
                    258:  */
                    259: void map_destroySession(ait_sess_t * __restrict Sess);
1.1       misho     260: 
                    261: /*
                    262:  * ipc_createSession() IPC Created session and allocated resources
1.4       misho     263:  *
                    264:  * @nSeed = Seed for securing key, if =-1 must add ready for use key
                    265:  * @nSize = Allocated shared memory size in bytes
1.1       misho     266:  * @Sess = Session item
1.4       misho     267:  * @... = If nSeed == -1 add ready for use key value
1.1       misho     268:  * return: 0 Ok successful, -1 error: not allocated resources
1.4       misho     269:  */
                    270: int ipc_createSession(int nSeed, long nSize, ait_sess_t * __restrict Sess, ...);
1.1       misho     271: /*
                    272:  * ipc_destroySession() IPC free shared resources
1.4       misho     273:  *
1.1       misho     274:  * @Sess = Session item
1.4       misho     275:  * return: none
                    276:  */
                    277: void ipc_destroySession(ait_sess_t * __restrict Sess);
1.1       misho     278: 
                    279: /*
                    280:  * map_attachSession() MMAP Attach to shared memory & return begin address
1.4       misho     281:  *
1.1       misho     282:  * @s = Session item
                    283:  * @procMem = Custom start address (optionl) *default must be 0*
                    284:  * return: NULL failed attach, !=NULL begin address of memory
1.4       misho     285:  */
                    286: void *map_attachSession(ait_sess_t * __restrict s, void *procMem);
1.1       misho     287: /*
                    288:  * map_detachSession() MMAP Detach from shared memory
1.4       misho     289:  *
1.1       misho     290:  * @s = Session item
1.4       misho     291:  * return: none
                    292:  */
                    293: void map_detachSession(ait_sess_t * __restrict s);
1.1       misho     294: 
                    295: /*
                    296:  * ipc_attachSession() IPC Attach to shared memory & return begin address
1.4       misho     297:  *
1.1       misho     298:  * @s = Session item
                    299:  * @procMem = Custom start address (optionl) *default must be 0*
                    300:  * return: NULL failed attach, !=NULL begin address of memory
1.4       misho     301:  */
                    302: void *ipc_attachSession(ait_sess_t * __restrict s, void *procMem);
1.1       misho     303: /*
                    304:  * ipc_detachSession() IPC Detach from shared memory
1.4       misho     305:  *
1.1       misho     306:  * @s = Session item
1.4       misho     307:  * return: none
                    308:  */
                    309: void ipc_detachSession(ait_sess_t * __restrict s);
1.1       misho     310: 
                    311: /*
1.4       misho     312:  * sess_isAttached() Check for attached shared memory
                    313:  *
1.2       misho     314:  * @s = Session item
                    315:  * return: -1 null session item, 0 not attached, 1 attached memory
1.4       misho     316:  */
                    317: inline int sess_isAttached(ait_sess_t * __restrict s);
1.2       misho     318: 
                    319: 
                    320: /*
1.1       misho     321:  * map_notSemaphore() MMAP negative block if semaphore isn`t signaled
1.4       misho     322:  *
1.1       misho     323:  * @s = Session item
1.4       misho     324:  * return: none
                    325:  */
                    326: void map_notSemaphore(ait_sess_t * __restrict s);
1.1       misho     327: /*
1.4       misho     328:  * map_isSemaphoreOK() MMAP Check semaphore
                    329:  *
1.1       misho     330:  * @s = Session item
                    331:  * return: -1 error: can`t return semaphore, 0 = false, 1 = true
1.4       misho     332:  */
                    333: int map_isSemaphoreOK(ait_sess_t * __restrict s);
1.1       misho     334: /*
1.4       misho     335:  * map_incSemaphore() MMAP unblock semaphore, increment semaphore
                    336:  *
1.1       misho     337:  * @s = Session item
                    338:  * return: 0 Ok, -1 error: can`t increment 
1.4       misho     339:  */
                    340: int map_incSemaphore(ait_sess_t * __restrict s);
1.1       misho     341: /*
                    342:  * map_decSemaphore() MMAP block semaphore, decrement semaphore
1.4       misho     343:  *
1.1       misho     344:  * @s = Session item
                    345:  * return: 0 Ok, -1 error: can`t decrement 
1.4       misho     346:  */
                    347: int map_decSemaphore(ait_sess_t * __restrict s);
1.1       misho     348: 
                    349: /*
                    350:  * ipc_notSemaphore() IPC negative block if semaphore isn`t signaled
1.4       misho     351:  *
1.1       misho     352:  * @s = Session item
1.4       misho     353:  * return: none
                    354:  */
                    355: void ipc_notSemaphore(ait_sess_t * __restrict s);
1.1       misho     356: /*
1.4       misho     357:  * ipc_isSemaphoreOK() IPC Check semaphore
                    358:  *
1.1       misho     359:  * @s = Session item
                    360:  * return: -1 error: can`t return semaphore, 0 = false, 1 = true
1.4       misho     361:  */
                    362: int ipc_isSemaphoreOK(ait_sess_t * __restrict s);
1.1       misho     363: /*
1.4       misho     364:  * ipc_incSemaphore() IPC unblock semaphore, increment semaphore
                    365:  *
1.1       misho     366:  * @s = Session item
                    367:  * return: 0 Ok, -1 error: can`t increment 
1.4       misho     368:  */
                    369: int ipc_incSemaphore(ait_sess_t * __restrict s);
1.1       misho     370: /*
                    371:  * ipc_decSemaphore() IPC block semaphore, decrement semaphore
1.4       misho     372:  *
1.1       misho     373:  * @s = Session item
                    374:  * return: 0 Ok, -1 error: can`t decrement 
1.4       misho     375:  */
                    376: int ipc_decSemaphore(ait_sess_t * __restrict s);
                    377: 
                    378: 
                    379: /* --------------------------------------------------------- */
1.1       misho     380: 
1.4       misho     381: #define ALLOC_MEMORY(sd, siz, s, ...)  (assert((s)), (s)->sess.create((sd), \
                    382:                                                        (siz), (s), ## __VA_ARGS__))
                    383: #define ATTACH_MEMORY(s)               (assert((s)), (s)->sess.attach((s), NULL))
                    384: #define DETACH_MEMORY(s)               do { assert((s)); (s)->sess.detach((s)); } while(0)
                    385: #define FREE_MEMORY(s)                 do { assert((s)); (s)->sess.destroy((s)); } while(0)
1.2       misho     386: 
1.4       misho     387: #define IS_SEMOK(s)                    (assert((s)), (s)->sess.isSemOK((s)))
                    388: #define INC_SEM(s)                     (assert((s)), (s)->sess.incSem((s)))
                    389: #define DEC_SEM(s)                     (assert((s)), (s)->sess.decSem((s)))
                    390: #define NOT_SEM(s)                     do { assert((s)); (s)->sess.notSem((s)); } while(0)
1.1       misho     391: 
1.4       misho     392: /* --------------------------------------------------------- */
1.1       misho     393: 
                    394: /*
1.2       misho     395:  * sess_FreeValues() Free all values from value array allocated from sess_GetValues()
1.4       misho     396:  *
1.2       misho     397:  * @ppsVals = Array strings
                    398:  * return: none
1.4       misho     399:  */
1.2       misho     400: inline void sess_FreeValues(char *** __restrict ppsVals);
                    401: /*
                    402:  * sess_GetValues() Get all values from session shared memory
1.4       misho     403:  *
1.2       misho     404:  * @s = Session item
                    405:  * @ppsVals = Return array strings
                    406:  * return: -1 error: in parameter, !=-1 count of returned strings in ppsVals (must be free after use!)
1.4       misho     407:  */
                    408: int sess_GetValues(ait_sess_t * __restrict s, char ***ppsVals);
1.2       misho     409: /*
1.1       misho     410:  * sess_GetValue() Get value from session shared memory from attribute
1.4       misho     411:  *
1.1       misho     412:  * @s = Session item
                    413:  * @csAttr = Attribute for search
                    414:  * @psVal = Return string buffer
                    415:  * @pnLen = Length of return string buffer, 
                    416:        // *{pnLen} input is max_size of buffer & output is really taken bytes
                    417:  * return: 0 not found, -1 error: in parameter, >0 get position, if define item merged with IS_DEF
1.4       misho     418:  */
                    419: int sess_GetValue(ait_sess_t * __restrict s, const char *csAttr, char *psVal, int *pnLen);
1.1       misho     420: /*
                    421:  * sess_DelValue() Delete item from session shared memory
1.4       misho     422:  *
1.1       misho     423:  * @s = Session item
                    424:  * @csAttr = Attribute for erasing
                    425:  * return: 0 Ok, -1 error: in parameter
1.4       misho     426:  */
                    427: int sess_DelValue(ait_sess_t * __restrict s, const char *csAttr);
1.1       misho     428: /*
                    429:  * sess_SetValue() Set item into session shared memory or update if find it
1.4       misho     430:  *
1.1       misho     431:  * @s = Session item
                    432:  * @csAttr = Attribute
                    433:  * @psVal = Value
                    434:  * return: 0 nothing, -1 error: in parameter, 
                    435:        >0 set position, if add item merged with IS_ADD and if define item merged with IS_DEF
1.4       misho     436:  */
                    437: int sess_SetValue(ait_sess_t * __restrict s, const char *csAttr, const char *psVal);
                    438: 
                    439: /*
                    440:  * sess_prepareSession() Attach to shared memory and de-marshaling data
                    441:  *
                    442:  * @s = Session
                    443:  * @useDirect = Use direct shared memory if !=0 or snapshot of data to array
                    444:  * return: NULL error or no data, !=NULL array with variables, 
                    445:  *             after use must free resources with sess_doneSession()
                    446:  */
                    447: array_t *sess_prepareSession(ait_sess_t * __restrict s, char useDirect);
                    448: /*
                    449:  * sess_doneSession() Free resources allocated with sess_prepareSession()
                    450:  *
                    451:  * @s = Session
                    452:  * @arr = Array with variables for free
                    453:  * return: none
                    454:  */
                    455: void sess_doneSession(ait_sess_t * __restrict s, array_t ** __restrict arr);
                    456: /*
                    457:  * sess_commitSession() Commit data to shared memory
                    458:  *
                    459:  * @s = Session
                    460:  * @arr = Array with variables for save
                    461:  * return -1 error or !=-1 size of stored variables into shared memory
                    462:  */
                    463: int sess_commitSession(ait_sess_t * __restrict s, array_t * __restrict arr);
1.1       misho     464: 
                    465: 
                    466: #endif

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>