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

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.2.2.3 ! misho       6: * $Id: aitsess.h,v 1.2.2.2 2011/08/21 14:00:43 misho Exp $
1.2       misho       7: *
1.2.2.1   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: 
                     15: Copyright 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
                     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.2.2.3 ! misho      50: #include <assert.h>
1.1       misho      51: #include <semaphore.h>
                     52: #include <sys/types.h>
                     53: 
1.2.2.2   misho      54: #define SHARED_UNKNOWN 0
1.1       misho      55: #define SHARED_IPC     1
                     56: #define SHARED_MAP     2
                     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  63
                     66: #define MAX_SEMNAME    14
                     67: 
                     68: 
                     69: typedef struct _tagSess {
                     70:        key_t   key;
                     71:        u_char  type;
                     72:        off_t   eom;
                     73:        void    *addr;
                     74:        off_t   offset;
                     75:        union {
                     76:                int     shmid;
                     77:                int     fd;
                     78:        } mem;
                     79:        union {
                     80:                int     semid;
                     81:                sem_t   *sid;
                     82:        } id;
                     83: } tagSess;
                     84: 
                     85: 
                     86: // -------------------------------------------------------
                     87: // sess_GetErrno() Get error code of last operation
                     88: inline int sess_GetErrno();
                     89: // sess_GetError() Get error text of last operation
                     90: inline const char *sess_GetError();
                     91: // -------------------------------------------------------
                     92: 
                     93: 
                     94: /*
                     95:  * initSession() Initializing session structure, if session file not exists creating with specified tech
1.2.2.2   misho      96:  * @pnID = Technology using in session. 
                     97:        SHARED_IPC IPC tech; SHARED_MAP BSD MemoryMap tech or if =NULL SHARED_IPC
1.1       misho      98:  * @csFName = Session filename for build key and identified
1.2.2.2   misho      99:  * @Sess = Session item, if =NULL allocate memory for session after use must be free!
1.1       misho     100:  * return: 0 OK new key created, -1 error: no memory or file not created, 1 OK key finded
                    101: */
1.2.2.2   misho     102: inline int initSession(int *pnID, const char *csFName, tagSess ** __restrict Sess);
1.1       misho     103: /*
                    104:  * freeSession() Free allocated memory for session item and delete session file if present name
                    105:  * @csFName = Session filename for delete, if NULL nothing delete
                    106:  * @Sess = Session item
                    107: */
                    108: inline void freeSession(const char *csFName, tagSess ** __restrict Sess);
                    109: 
                    110: /*
                    111:  * map_createSession() MMAP Created session and allocated resources
                    112:  * @csFName = Session name for identified
                    113:  * @cnSeed = Seed for securing key
                    114:  * @cnSize = Allocated shared memory size in bytes
                    115:  * @Sess = Session item
                    116:  * return: 0 Ok successful, -1 error: not allocated resources
                    117: */
                    118: int map_createSession(const char *csFName, const int cnSeed, const u_int cnSize, tagSess ** __restrict Sess);
                    119: /*
                    120:  * map_destroySession() MMAP free shared resources
                    121:  * @csFName = Session name for delete
                    122:  * @Sess = Session item
                    123: */
                    124: void map_destroySession(const char *csFName, tagSess ** __restrict Sess);
                    125: 
                    126: /*
                    127:  * ipc_createSession() IPC Created session and allocated resources
                    128:  * @csFName = Session name for identified
                    129:  * @cnSeed = Seed for securing key
                    130:  * @cnSize = Allocated shared memory size in bytes
                    131:  * @Sess = Session item
                    132:  * return: 0 Ok successful, -1 error: not allocated resources
                    133: */
                    134: int ipc_createSession(const char *csFName, const int cnSeed, const u_int cnSize, tagSess ** __restrict Sess);
                    135: /*
                    136:  * ipc_destroySession() IPC free shared resources
                    137:  * @csFName = Session name for delete
                    138:  * @Sess = Session item
                    139: */
                    140: void ipc_destroySession(const char *csFName, tagSess ** __restrict Sess);
                    141: 
                    142: /*
                    143:  * map_attachSession() MMAP Attach to shared memory & return begin address
                    144:  * @s = Session item
                    145:  * @procMem = Custom start address (optionl) *default must be 0*
                    146:  * return: NULL failed attach, !=NULL begin address of memory
                    147: */
                    148: inline void *map_attachSession(tagSess * __restrict s, void *procMem);
                    149: /*
                    150:  * map_detachSession() MMAP Detach from shared memory
                    151:  * @s = Session item
                    152: */
                    153: inline void map_detachSession(tagSess * __restrict s);
                    154: 
                    155: /*
                    156:  * ipc_attachSession() IPC Attach to shared memory & return begin address
                    157:  * @s = Session item
                    158:  * @procMem = Custom start address (optionl) *default must be 0*
                    159:  * return: NULL failed attach, !=NULL begin address of memory
                    160: */
                    161: inline void *ipc_attachSession(tagSess * __restrict s, void *procMem);
                    162: /*
                    163:  * ipc_detachSession() IPC Detach from shared memory
                    164:  * @s = Session item
                    165: */
                    166: inline void ipc_detachSession(tagSess * __restrict s);
                    167: 
                    168: /*
1.2       misho     169:  * isAttached() Check for mapped/(attached) shared memory
                    170:  * @s = Session item
                    171:  * return: -1 null session item, 0 not attached, 1 attached memory
                    172: */
                    173: inline int isAttached(tagSess * __restrict s);
                    174: 
                    175: 
                    176: /*
1.1       misho     177:  * map_notSemaphore() MMAP negative block if semaphore isn`t signaled
                    178:  * @s = Session item
                    179: */
                    180: inline void map_notSemaphore(tagSess * __restrict s);
                    181: /*
                    182:  * map_isSemaphored() MMAP Check semaphore
                    183:  * @s = Session item
                    184:  * return: -1 error: can`t return semaphore, 0 = false, 1 = true
                    185: */
                    186: inline int map_isSemaphored(tagSess * __restrict s);
                    187: /*
                    188:  * map_addSemaphore() MMAP unblock semaphore, increment semaphore
                    189:  * @s = Session item
                    190:  * return: 0 Ok, -1 error: can`t increment 
                    191: */
                    192: inline int map_addSemaphore(tagSess * __restrict s);
                    193: /*
                    194:  * map_decSemaphore() MMAP block semaphore, decrement semaphore
                    195:  * @s = Session item
                    196:  * return: 0 Ok, -1 error: can`t decrement 
                    197: */
                    198: inline int map_decSemaphore(tagSess * __restrict s);
                    199: 
                    200: /*
                    201:  * ipc_notSemaphore() IPC negative block if semaphore isn`t signaled
                    202:  * @s = Session item
                    203: */
                    204: inline void ipc_notSemaphore(tagSess * __restrict s);
                    205: /*
                    206:  * ipc_isSemaphored() IPC Check semaphore
                    207:  * @s = Session item
                    208:  * return: -1 error: can`t return semaphore, 0 = false, 1 = true
                    209: */
                    210: inline int ipc_isSemaphored(tagSess * __restrict s);
                    211: /*
                    212:  * ipc_addSemaphore() IPC unblock semaphore, increment semaphore
                    213:  * @s = Session item
                    214:  * return: 0 Ok, -1 error: can`t increment 
                    215: */
                    216: inline int ipc_addSemaphore(tagSess * __restrict s);
                    217: /*
                    218:  * ipc_decSemaphore() IPC block semaphore, decrement semaphore
                    219:  * @s = Session item
                    220:  * return: 0 Ok, -1 error: can`t decrement 
                    221: */
                    222: inline int ipc_decSemaphore(tagSess * __restrict s);
                    223: 
1.2       misho     224: 
1.1       misho     225: // ---------------------------------------------------------
                    226: //
                    227: //  Lazy macros for lazy programmers :-) by Michael Pounov; Optimizing work with sessions!
                    228: //
                    229: 
1.2.2.3 ! misho     230: #define DESTROY_SESSION(fname, s)      do { assert((s)); assert((*s)); \
1.2       misho     231:                                                switch (((*s))->type) { \
1.1       misho     232:                                                        case SHARED_IPC: \
                    233:                                                                         ipc_destroySession((fname), (s)); \
                    234:                                                                         break; \
                    235:                                                        case SHARED_MAP: \
                    236:                                                                         map_destroySession((fname), (s)); \
                    237:                                                                         break; \
                    238:                                                } \
                    239:                                        } while(0)
                    240: 
1.2.2.3 ! misho     241: #define ATTACH_MEMORY(s)               do { assert((s)); \
1.1       misho     242:                                                switch ((s)->type) { \
                    243:                                                        case SHARED_IPC: \
1.2       misho     244:                                                                         ipc_attachSession((s), 0); \
1.1       misho     245:                                                                         break; \
                    246:                                                        case SHARED_MAP: \
1.2       misho     247:                                                                         map_attachSession((s), 0); \
1.1       misho     248:                                                                         break; \
                    249:                                                } \
                    250:                                        } while(0)
                    251: 
1.2.2.3 ! misho     252: #define DETACH_MEMORY(s)               do { assert((s)); \
1.1       misho     253:                                                switch ((s)->type) { \
                    254:                                                        case SHARED_IPC: \
                    255:                                                                         ipc_detachSession((s)); \
                    256:                                                                         break; \
                    257:                                                        case SHARED_MAP: \
                    258:                                                                         map_detachSession((s)); \
                    259:                                                                         break; \
                    260:                                                } \
                    261:                                        } while(0)
                    262: 
1.2.2.3 ! misho     263: #define NOT_SEMAPHORE(s)       do { assert((s)); \
1.1       misho     264:                                        switch ((s)->type) { \
                    265:                                                case SHARED_IPC: \
                    266:                                                                 ipc_notSemaphore((s)); \
                    267:                                                                 break; \
                    268:                                                case SHARED_MAP: \
                    269:                                                                 map_notSemaphore((s)); \
                    270:                                                                 break; \
                    271:                                        } \
                    272:                                } while(0)
                    273: 
1.2.2.3 ! misho     274: #define IS_SEMAPHORED(s, ret)  do { assert((s)); \
1.1       misho     275:                                        switch ((s)->type) { \
                    276:                                                case SHARED_IPC: \
                    277:                                                                 (ret) = ipc_isSemaphored((s)); \
                    278:                                                                 break; \
                    279:                                                case SHARED_MAP: \
                    280:                                                                 (ret) = map_isSemaphored((s)); \
                    281:                                                                 break; \
                    282:                                                default: \
                    283:                                                         (ret) = -1; \
                    284:                                        } \
                    285:                                } while(0)
                    286: 
1.2.2.3 ! misho     287: #define ADD_SEMAPHORE(s, ret)  do { assert((s)); \
1.1       misho     288:                                        switch ((s)->type) { \
                    289:                                                case SHARED_IPC: \
                    290:                                                                 (ret) = ipc_addSemaphore((s)); \
                    291:                                                                 break; \
                    292:                                                case SHARED_MAP: \
                    293:                                                                 (ret) = map_addSemaphore((s)); \
                    294:                                                                 break; \
                    295:                                                default: \
                    296:                                                         (ret) = -1; \
                    297:                                        } \
                    298:                                } while(0)
                    299: 
1.2.2.3 ! misho     300: #define DEC_SEMAPHORE(s, ret)  do { assert((s)); \
1.1       misho     301:                                        switch ((s)->type) { \
                    302:                                                case SHARED_IPC: \
                    303:                                                                 (ret) = ipc_decSemaphore((s)); \
                    304:                                                                 break; \
                    305:                                                case SHARED_MAP: \
                    306:                                                                 (ret) = map_decSemaphore((s)); \
                    307:                                                                 break; \
                    308:                                                default: \
                    309:                                                         (ret) = -1; \
                    310:                                        } \
                    311:                                } while(0)
                    312: 
                    313: // ---------------------------------------------------------
                    314: 
                    315: /*
1.2       misho     316:  * sess_FreeValues() Free all values from value array allocated from sess_GetValues()
                    317:  * @ppsVals = Array strings
                    318:  * return: none
                    319: */
                    320: inline void sess_FreeValues(char *** __restrict ppsVals);
                    321: /*
                    322:  * sess_GetValues() Get all values from session shared memory
                    323:  * @s = Session item
                    324:  * @ppsVals = Return array strings
                    325:  * return: -1 error: in parameter, !=-1 count of returned strings in ppsVals (must be free after use!)
                    326: */
                    327: int sess_GetValues(tagSess * __restrict s, char ***ppsVals);
                    328: /*
1.1       misho     329:  * sess_GetValue() Get value from session shared memory from attribute
                    330:  * @s = Session item
                    331:  * @csAttr = Attribute for search
                    332:  * @psVal = Return string buffer
                    333:  * @pnLen = Length of return string buffer, 
                    334:        // *{pnLen} input is max_size of buffer & output is really taken bytes
                    335:  * return: 0 not found, -1 error: in parameter, >0 get position, if define item merged with IS_DEF
                    336: */
                    337: int sess_GetValue(tagSess * __restrict s, const char *csAttr, char *psVal, int *pnLen);
                    338: /*
                    339:  * sess_DelValue() Delete item from session shared memory
                    340:  * @s = Session item
                    341:  * @csAttr = Attribute for erasing
                    342:  * return: 0 Ok, -1 error: in parameter
                    343: */
                    344: int sess_DelValue(tagSess * __restrict s, const char *csAttr);
                    345: /*
                    346:  * sess_SetValue() Set item into session shared memory or update if find it
                    347:  * @s = Session item
                    348:  * @csAttr = Attribute
                    349:  * @psVal = Value
                    350:  * return: 0 nothing, -1 error: in parameter, 
                    351:        >0 set position, if add item merged with IS_ADD and if define item merged with IS_DEF
                    352: */
                    353: int sess_SetValue(tagSess * __restrict s, const char *csAttr, const char *psVal);
                    354: 
                    355: 
                    356: #endif

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