Annotation of libaitio/inc/aitsess.h, revision 1.2

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 $
        !             6: * $Id: aitsess.h,v 1.1.2.3 2013/03/13 14:51:38 misho Exp $
        !             7: *
        !             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: 
        !            15: Copyright 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
        !            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: */
        !            46: #ifndef __AITSESS_H
        !            47: #define __AITSESS_H
        !            48: 
        !            49: 
        !            50: #include <pthread.h>
        !            51: #include <semaphore.h>
        !            52: #include <elwix.h>
        !            53: 
        !            54: #define SHARED_UNKNOWN -1
        !            55: #define SHARED_IPC     0
        !            56: #define SHARED_MAP     1
        !            57: 
        !            58: #define IS_VAL         0x0
        !            59: #define IS_ADD         0x40000000
        !            60: #define IS_DEF         0x80000000
        !            61: 
        !            62: #define ISNEW(x)       (((x) & IS_ADD) == IS_ADD)
        !            63: #define ISDEF(x)       (((x) & IS_DEF) == IS_DEF)
        !            64: 
        !            65: #define MAX_ATTRIBUTE  64
        !            66: #define MAX_SEMNAME    14
        !            67: 
        !            68: 
        !            69: /* Shared memory session */
        !            70: 
        !            71: typedef struct tagSess {
        !            72:        key_t   key;
        !            73:        char    type;
        !            74:        char    zcpy;
        !            75: 
        !            76:        char    name[BUFSIZ];
        !            77:        off_t   eom;
        !            78:        void    *addr;
        !            79:        off_t   offset;
        !            80:        union {
        !            81:                int     shmid;
        !            82:                int     fd;
        !            83:        } mem;
        !            84:        union {
        !            85:                int     semid;
        !            86:                sem_t   *sid;
        !            87:        } id;
        !            88: 
        !            89:        struct {
        !            90:                int (*create)(int, long, void *, ...);
        !            91:                void (*destroy)(void *);
        !            92:                void *(*attach)(void *, void *);
        !            93:                void (*detach)(void *);
        !            94:                void (*notSem)(void *);
        !            95:                int (*isSemOK)(void *);
        !            96:                int (*incSem)(void *);
        !            97:                int (*decSem)(void *);
        !            98:        } sess;
        !            99: } ait_sess_t;
        !           100: 
        !           101: 
        !           102: /*
        !           103:  * sess_initSession() - Initializing session structure, 
        !           104:  *                     if session file not exists creating with specified tech
        !           105:  *
        !           106:  * @id = Technology using in session. SHARED_IPC IPC tech or SHARED_MAP BSD MemoryMap tech
        !           107:  * @csFName = Session filename for build key and identified
        !           108:  * @Sess = Session item, if =NULL allocate memory for session after use must be free!
        !           109:  * return: 0 OK new key created, -1 error: no memory or file not created, 1 OK key finded
        !           110:  */
        !           111: int sess_initSession(int id, const char *csFName, ait_sess_t ** __restrict Sess);
        !           112: /*
        !           113:  * sess_freeSession() - Free allocated memory for session item and delete session file if present name
        !           114:  *
        !           115:  * @Sess = Session item
        !           116:  * return: none
        !           117:  */
        !           118: void sess_freeSession(ait_sess_t ** __restrict Sess);
        !           119: 
        !           120: /*
        !           121:  * map_createSession() - MMAP Created session and allocated resources
        !           122:  *
        !           123:  * @nSeed = Seed for securing key, if =-1 must add ready for use key
        !           124:  * @nSize = Allocated shared memory size in bytes
        !           125:  * @Sess = Session item
        !           126:  * @... = If nSeed == -1 add ready for use key value
        !           127:  * return: 0 Ok successful, -1 error: not allocated resources
        !           128:  */
        !           129: int map_createSession(int nSeed, long nSize, ait_sess_t * __restrict Sess, ...);
        !           130: /*
        !           131:  * map_destroySession() - MMAP free shared resources
        !           132:  *
        !           133:  * @Sess = Session item
        !           134:  * return: none
        !           135:  */
        !           136: void map_destroySession(ait_sess_t * __restrict Sess);
        !           137: 
        !           138: /*
        !           139:  * ipc_createSession() - IPC Created session and allocated resources
        !           140:  *
        !           141:  * @nSeed = Seed for securing key, if =-1 must add ready for use key
        !           142:  * @nSize = Allocated shared memory size in bytes
        !           143:  * @Sess = Session item
        !           144:  * @... = If nSeed == -1 add ready for use key value
        !           145:  * return: 0 Ok successful, -1 error: not allocated resources
        !           146:  */
        !           147: int ipc_createSession(int nSeed, long nSize, ait_sess_t * __restrict Sess, ...);
        !           148: /*
        !           149:  * ipc_destroySession() - IPC free shared resources
        !           150:  *
        !           151:  * @Sess = Session item
        !           152:  * return: none
        !           153:  */
        !           154: void ipc_destroySession(ait_sess_t * __restrict Sess);
        !           155: 
        !           156: /*
        !           157:  * map_attachSession() - MMAP Attach to shared memory & return begin address
        !           158:  *
        !           159:  * @s = Session item
        !           160:  * @procMem = Custom start address (optionl) *default must be 0*
        !           161:  * return: NULL failed attach, !=NULL begin address of memory
        !           162:  */
        !           163: void *map_attachSession(ait_sess_t * __restrict s, void *procMem);
        !           164: /*
        !           165:  * map_detachSession() - MMAP Detach from shared memory
        !           166:  *
        !           167:  * @s = Session item
        !           168:  * return: none
        !           169:  */
        !           170: void map_detachSession(ait_sess_t * __restrict s);
        !           171: 
        !           172: /*
        !           173:  * ipc_attachSession() - IPC Attach to shared memory & return begin address
        !           174:  *
        !           175:  * @s = Session item
        !           176:  * @procMem = Custom start address (optionl) *default must be 0*
        !           177:  * return: NULL failed attach, !=NULL begin address of memory
        !           178:  */
        !           179: void *ipc_attachSession(ait_sess_t * __restrict s, void *procMem);
        !           180: /*
        !           181:  * ipc_detachSession() - IPC Detach from shared memory
        !           182:  *
        !           183:  * @s = Session item
        !           184:  * return: none
        !           185:  */
        !           186: void ipc_detachSession(ait_sess_t * __restrict s);
        !           187: 
        !           188: /*
        !           189:  * sess_isAttached() - Check for attached shared memory
        !           190:  *
        !           191:  * @s = Session item
        !           192:  * return: -1 null session item, 0 not attached, 1 attached memory
        !           193:  */
        !           194: inline int sess_isAttached(ait_sess_t * __restrict s);
        !           195: 
        !           196: 
        !           197: /*
        !           198:  * map_notSemaphore() - MMAP negative block if semaphore isn`t signaled
        !           199:  *
        !           200:  * @s = Session item
        !           201:  * return: none
        !           202:  */
        !           203: void map_notSemaphore(ait_sess_t * __restrict s);
        !           204: /*
        !           205:  * map_isSemaphoreOK() - MMAP Check semaphore
        !           206:  *
        !           207:  * @s = Session item
        !           208:  * return: -1 error: can`t return semaphore, 0 = false, 1 = true
        !           209:  */
        !           210: int map_isSemaphoreOK(ait_sess_t * __restrict s);
        !           211: /*
        !           212:  * map_incSemaphore() - MMAP unblock semaphore, increment semaphore
        !           213:  *
        !           214:  * @s = Session item
        !           215:  * return: 0 Ok, -1 error: can`t increment 
        !           216:  */
        !           217: int map_incSemaphore(ait_sess_t * __restrict s);
        !           218: /*
        !           219:  * map_decSemaphore() - MMAP block semaphore, decrement semaphore
        !           220:  *
        !           221:  * @s = Session item
        !           222:  * return: 0 Ok, -1 error: can`t decrement 
        !           223:  */
        !           224: int map_decSemaphore(ait_sess_t * __restrict s);
        !           225: 
        !           226: /*
        !           227:  * ipc_notSemaphore() - IPC negative block if semaphore isn`t signaled
        !           228:  *
        !           229:  * @s = Session item
        !           230:  * return: none
        !           231:  */
        !           232: void ipc_notSemaphore(ait_sess_t * __restrict s);
        !           233: /*
        !           234:  * ipc_isSemaphoreOK() - IPC Check semaphore
        !           235:  *
        !           236:  * @s = Session item
        !           237:  * return: -1 error: can`t return semaphore, 0 = false, 1 = true
        !           238:  */
        !           239: int ipc_isSemaphoreOK(ait_sess_t * __restrict s);
        !           240: /*
        !           241:  * ipc_incSemaphore() - IPC unblock semaphore, increment semaphore
        !           242:  *
        !           243:  * @s = Session item
        !           244:  * return: 0 Ok, -1 error: can`t increment 
        !           245:  */
        !           246: int ipc_incSemaphore(ait_sess_t * __restrict s);
        !           247: /*
        !           248:  * ipc_decSemaphore() - IPC block semaphore, decrement semaphore
        !           249:  *
        !           250:  * @s = Session item
        !           251:  * return: 0 Ok, -1 error: can`t decrement 
        !           252:  */
        !           253: int ipc_decSemaphore(ait_sess_t * __restrict s);
        !           254: 
        !           255: 
        !           256: /* --------------------------------------------------------- */
        !           257: 
        !           258: #define ALLOC_MEMORY(sd, siz, s, ...)  (assert((s)), (s)->sess.create((sd), \
        !           259:                                                        (siz), (s), ## __VA_ARGS__))
        !           260: #define ATTACH_MEMORY(s)               (assert((s)), (s)->sess.attach((s), NULL))
        !           261: #define DETACH_MEMORY(s)               do { assert((s)); (s)->sess.detach((s)); } while(0)
        !           262: #define FREE_MEMORY(s)                 do { assert((s)); (s)->sess.destroy((s)); } while(0)
        !           263: 
        !           264: #define IS_SEMOK(s)                    (assert((s)), (s)->sess.isSemOK((s)))
        !           265: #define INC_SEM(s)                     (assert((s)), (s)->sess.incSem((s)))
        !           266: #define DEC_SEM(s)                     (assert((s)), (s)->sess.decSem((s)))
        !           267: #define NOT_SEM(s)                     do { assert((s)); (s)->sess.notSem((s)); } while(0)
        !           268: 
        !           269: /* --------------------------------------------------------- */
        !           270: 
        !           271: /*
        !           272:  * sess_FreeValues() - Free all values from value array allocated from sess_GetValues()
        !           273:  *
        !           274:  * @ppsVals = Array strings
        !           275:  * return: none
        !           276:  */
        !           277: inline void sess_FreeValues(char *** __restrict ppsVals);
        !           278: /*
        !           279:  * sess_GetValues() - Get all values from session shared memory
        !           280:  *
        !           281:  * @s = Session item
        !           282:  * @ppsVals = Return array strings
        !           283:  * return: -1 error: in parameter, !=-1 count of returned strings in ppsVals 
        !           284:  *             (must be sess_FreeValues after use!)
        !           285:  */
        !           286: int sess_GetValues(ait_sess_t * __restrict s, char ***ppsVals);
        !           287: /*
        !           288:  * sess_GetValue() - Get value from session shared memory from attribute
        !           289:  *
        !           290:  * @s = Session item
        !           291:  * @csAttr = Attribute for search
        !           292:  * @psVal = Return string buffer
        !           293:  * @pnLen = Length of return string buffer, 
        !           294:        // *{pnLen} input is max_size of buffer & output is really taken bytes
        !           295:  * return: 0 not found, -1 error: in parameter, >0 get position, 
        !           296:  *     if define item merged with IS_DEF
        !           297:  */
        !           298: int sess_GetValue(ait_sess_t * __restrict s, const char *csAttr, char *psVal, int *pnLen);
        !           299: /*
        !           300:  * sess_DelValue() - Delete item from session shared memory
        !           301:  *
        !           302:  * @s = Session item
        !           303:  * @csAttr = Attribute for erasing
        !           304:  * return: 0 Ok, -1 error: in parameter
        !           305:  */
        !           306: int sess_DelValue(ait_sess_t * __restrict s, const char *csAttr);
        !           307: /*
        !           308:  * sess_SetValue() - Set item into session shared memory or update if exists
        !           309:  *
        !           310:  * @s = Session item
        !           311:  * @csAttr = Attribute
        !           312:  * @psVal = Value
        !           313:  * return: 0 nothing, -1 error: in parameter, 
        !           314:        >0 set position, if add item merged with IS_ADD and if define item merged with IS_DEF
        !           315:  */
        !           316: int sess_SetValue(ait_sess_t * __restrict s, const char *csAttr, const char *psVal);
        !           317: 
        !           318: /*
        !           319:  * sess_prepareSession() - Attach to shared memory and de-marshaling data
        !           320:  *
        !           321:  * @s = Session
        !           322:  * @useDirect = Use direct shared memory if !=0 or snapshot of data to array
        !           323:  * return: NULL error or no data, !=NULL array with variables, 
        !           324:  *             after use must free resources with sess_doneSession()
        !           325:  */
        !           326: array_t *sess_prepareSession(ait_sess_t * __restrict s, char useDirect);
        !           327: /*
        !           328:  * sess_doneSession() - Free resources allocated with sess_prepareSession()
        !           329:  *
        !           330:  * @s = Session
        !           331:  * @arr = Array with variables for free
        !           332:  * return: none
        !           333:  */
        !           334: void sess_doneSession(ait_sess_t * __restrict s, array_t ** __restrict arr);
        !           335: /*
        !           336:  * sess_commitSession() - Commit data to shared memory
        !           337:  *
        !           338:  * @s = Session
        !           339:  * @arr = Array with variables for save
        !           340:  * return -1 error or !=-1 size of stored variables into shared memory
        !           341:  */
        !           342: int sess_commitSession(ait_sess_t * __restrict s, array_t * __restrict arr);
        !           343: 
        !           344: 
        !           345: #endif

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