1 /* 2 * %CopyrightBegin% 3 * 4 * Copyright Ericsson AB 2001-2016. All Rights Reserved. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * %CopyrightEnd% 19 * 20 21 */ 22 #ifndef _RECLAIM_H 23 #define _RECLAIM_H 24 25 26 /* The Erlang release for VxWorks includes a simple mechanism for 27 "resource reclamation" at task exit - it allows replacement of the 28 functions that open/close "files" and malloc/free memory with versions 29 that keep track, to be able to "reclaim" file descriptors and memory 30 when a task exits (regardless of *how* it exits). 31 32 The interface to this mechanism is made available via this file, 33 with the following caveats: 34 35 - The interface may change (or perhaps even be removed, though that 36 isn't likely until VxWorks itself provides similar functionality) 37 in future releases - i.e. you must always use the version of this 38 file that comes with the Erlang release you are using. 39 40 - Disaster is guaranteed if you use the mechanism incorrectly (see 41 below for the correct way), e.g. allocate memory with the "tracking" 42 version of malloc() and free it with the "standard" version of free(). 43 44 - The mechanism (of course) incurs some performance penalty - thus 45 for a simple program you may be better off with careful programming, 46 making sure that you do whatever close()/free()/etc calls that are 47 appropriate at all exit points (though if you need to guard against 48 taskDelete() etc, things get messy...). 49 50 To use the mechanism, simply program your application normally, i.e. 51 use open()/close()/malloc()/free() etc as usual, but #include this 52 file before any usage of the relevant functions. NOTE: To avoid the 53 "disaster" mentioned above, you *must* #include it in *all* (or none) 54 of the files that manipulate a particular file descriptor, allocated 55 memory area, etc. 56 57 Before any task that uses this utility is loaded (which includes the 58 erlang emulator), the reclaim.o object file has to be loaded and 59 the function reclaim_init() has to be called. reclaim_init should be called 60 only _ONCE_ in a systems lifetime and has only a primitive guard 61 against multiple calls (i.e. a global variable is checked). Therefore 62 the initialization should occur either in the start script of the system 63 or (even better) in the usrInit() part of system initialization. The 64 object file itself should be loaded only once, so linking it with the 65 kernel is a good idea, linking with each application is an extremely bad 66 dito. Make really sure that it's loaded _before_ any application that 67 uses it if You want to load it in the startup script. 68 69 If You dont want to have #define's for the posix/stdio names 70 of the file/memory operations (i.e. no #define malloc save_malloc etc), 71 #define RECLAIM_NO_ALIAS in Your source before reclaim.h is included. 72 */ 73 74 #include <vxWorks.h> /* STATUS, size_t */ 75 #include <sockLib.h> /* struct sockaddr */ 76 #include <stdio.h> /* FILE */ 77 78 #if defined(__STDC__) 79 #define _RECLAIM_DECL_FUN(RetType, FunName, ParamList) \ 80 extern RetType FunName##ParamList 81 #define _RECLAIM_VOID_PTR void * 82 #define _RECLAIM_VOID_PARAM void 83 #define _RECLAIM_VOID_RETURN void 84 #elif defined(__cplusplus) 85 #define _RECLAIM_DECL_FUN(RetType, FunName, ParamList) \ 86 extern "C" RetType FunName##ParamList 87 #define _RECLAIM_VOID_PTR void * 88 #define _RECLAIM_VOID_PARAM 89 #define _RECLAIM_VOID_RETURN void 90 #else 91 #define _RECLAIM_DECL_FUN(RetType, FunName, Ignore) extern RetType FunName() 92 #define DECLARE_FUNCTION_TYPE(RetType, Type, PList) typedef RetType (* Type)() 93 #define _RECLAIM_VOID_PTR char * 94 #define _RECLAIM_VOID_PARAM 95 #define _RECLAIM_VOID_RETURN 96 #endif /* __STDC__ / __cplusplus */ 97 98 /* Initialize the facility, on a per system basis. */ 99 _RECLAIM_DECL_FUN(STATUS, reclaim_init, (_RECLAIM_VOID_PARAM)); 100 101 /* File descriptor operations */ 102 _RECLAIM_DECL_FUN(int,save_open,(char *, int, ...)); 103 _RECLAIM_DECL_FUN(int,save_creat,(char *, int)); 104 _RECLAIM_DECL_FUN(int,save_socket,(int, int, int)); 105 _RECLAIM_DECL_FUN(int,save_accept,(int, struct sockaddr *, int *)); 106 _RECLAIM_DECL_FUN(int,save_close,(int)); 107 /* Interface to add an fd to what's reclaimed even though it's not open with 108 one of the above functions */ 109 _RECLAIM_DECL_FUN(_RECLAIM_VOID_RETURN, save_fd, (int fd)); 110 #ifndef RECLAIM_NO_ALIAS 111 #define open save_open 112 #define creat save_creat 113 #define socket save_socket 114 #define accept save_accept 115 #define close save_close 116 #endif 117 /* Stdio file operations */ 118 _RECLAIM_DECL_FUN(FILE *, save_fopen, (char *, char *)); 119 _RECLAIM_DECL_FUN(FILE *, save_fdopen, (int, char *)); 120 _RECLAIM_DECL_FUN(FILE *, save_freopen, (char *, char *, FILE *)); 121 _RECLAIM_DECL_FUN(int, save_fclose, (FILE *)); 122 /* XXX Should do opendir/closedir too... */ 123 #ifndef RECLAIM_NO_ALIAS 124 #define fopen save_fopen 125 #define fdopen save_fdopen 126 #define freopen save_freopen 127 #define fclose save_fclose 128 #endif 129 /* Memory allocation */ 130 _RECLAIM_DECL_FUN(_RECLAIM_VOID_PTR, save_malloc, (size_t)); 131 _RECLAIM_DECL_FUN(_RECLAIM_VOID_PTR, save_calloc, (size_t, size_t)); 132 _RECLAIM_DECL_FUN(_RECLAIM_VOID_PTR, save_realloc, 133 (_RECLAIM_VOID_PTR, size_t)); 134 _RECLAIM_DECL_FUN(void, save_free, (_RECLAIM_VOID_PTR)); 135 _RECLAIM_DECL_FUN(void, save_cfree, (_RECLAIM_VOID_PTR)); 136 #ifndef RECLAIM_NO_ALIAS 137 #define malloc save_malloc 138 #define calloc save_calloc 139 #define realloc save_realloc 140 #define free save_free 141 #define cfree save_cfree 142 #endif 143 /* Generic interfaces to malloc etc... */ 144 _RECLAIM_DECL_FUN(_RECLAIM_VOID_PTR, plain_malloc, (size_t)); 145 _RECLAIM_DECL_FUN(_RECLAIM_VOID_PTR, plain_realloc, 146 (_RECLAIM_VOID_PTR, size_t)); 147 _RECLAIM_DECL_FUN(void, plain_free, (_RECLAIM_VOID_PTR)); 148 #endif /* _RECLAIM_H */ 149 150 151 152 153