/src/wrappers/common/library/wrapper.e
Specman e | 137 lines | 64 code | 13 blank | 60 comment | 3 complexity | e77571d195e9a10b7d1c0ff5fe85edd2 MD5 | raw file
1note 2 description: 3 "Deferred class handling low-level C interfaces. Its heirs will fully expose each other their internals." 4 copyright: 5 "[ 6 Copyright (C) 2005-2017: ,2008 Paolo Redaelli 7 8 This library is free software; you can redistribute it and/or 9 modify it under the terms of the GNU Lesser General Public License 10 as published by the Free Software Foundation; either version 2.1 of 11 the License, or (at your option) any later version. 12 13 This library is distributed in the hope that it will be useful, but 14 WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public 19 License along with this library; if not, write to the Free Software 20 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 21 02110-1301 USA 22 ]" 23 24deferred class WRAPPER 25 -- Deferred class handling low-level C interfaces. Its heirs will fully 26 -- expose each other their internals. 27 -- 28 -- No assumption is made on memory handling; to create a proper wrapper for 29 -- it the developer shall inherit both from this class and from classes 30 -- providing memory handling behaviour, depending on how structure's memory 31 -- shall be handled. This is decided case-by-case by C library. 32 -- 33 -- Currently available memory handling classes are: 34 -- 35 -- C_OWNED: memory is always handled by the underlying C library. 36 -- 37 -- EIFFEL_OWNED: once created memory is fully handled by Eiffel runtime, 38 -- usually with the Garbage Collector. 39 -- 40 -- GLOBALLY_CACHED: Until disposed by Eiffel the wrapper registered in 41 -- wrappers dictionary will be the unique wrapper used on the Eiffel side. 42 -- 43 -- MIXED_MEMORY_HANDLING: whose memory can either by handled by the Eiffel 44 -- library or by the underlying C code. Who handles memory is decided on a 45 -- per-object based on the value of the flag `is_shared': handle will not 46 -- be freed on dispose of the Eiffel wrapper object, when `is_shared' 47 -- true. 48 -- 49 -- REFERENCE_COUNTED: memory is handled throught reference counting, i.e. 50 -- GObject 51 -- 52 -- Previous design was a black-or-white design either Eiffel-owned or not: 53 -- C_STRUCT's are "owned" by the Eiffel code, and the Eiffel side should 54 -- keep then longest lived reference to this struct. This allows us to 55 -- forget about wrapping for this objects. If you have to share this 56 -- struct and/or will have pointers to it around that will outlive the 57 -- wrapper, please use SHARED_C_STRUCT 58 59inherit 60 DISPOSABLE 61 -- we really should redefine is_equal and copy for all wrapper classes 62 -- WRAPPER conforms to ANY, because sometimes we need to get them via a 63 -- POINTER.to_any operation 64 undefine is_equal, copy 65 end 66 ANY 67 -- we really should redefine is_equal and copy for all wrapper classes 68 undefine is_equal, copy 69 end 70 71insert 72 WRAPPER_HANDLER 73 -- to access `null_or', `exceptions' strings and external calls 74 POINTER_HANDLING 75 -- to access `address_of' and `content_of' 76 STDLIB_EXTERNALS 77 STRING_EXTERNALS 78 STANDARD_C_LIBRARY_TYPES 79 export 80 {} all -- hide all underlying low-level code 81 end 82 83feature {WRAPPER, WRAPPER_HANDLER} -- Implementation 84 from_external_pointer (a_ptr: POINTER) 85 do 86 handle := a_ptr 87 ensure 88 handle = a_ptr 89 end 90 -- is_null: BOOLEAN 91 -- do 92 -- Result := handle.is_null 93 -- ensure 94 -- definition: Result = handle.is_null 95 -- end 96 -- is_not_null: BOOLEAN 97 -- do 98 -- Result := handle.is_not_null 99 -- ensure 100 -- definition: Result = handle.is_not_null 101 -- end 102 103 set_handle (a_ptr: POINTER) 104 -- Set a non-null handle. Raises an No_more_memory exception 105 -- if a_ptr.is_null. Use this, if you want to check the 106 -- result of some external allocation function. 107 do 108 if a_ptr.is_null then 109 raise_exception(No_more_memory) 110 end 111 handle := a_ptr 112 ensure 113 definition: handle = a_ptr 114 not_null: handle.is_not_null 115 end 116 117 handle: POINTER 118 -- Pointer to the underlying C "thing" (i.e. a struct) 119 120 reference: POINTER 121 -- The address of `handle'. Usuful to be passed to C 122 -- functions that asks for pointer to pointer to struct 123 -- (i.e. "GError **error") 124 do 125 Result := address_of(handle) 126 end 127 128feature {WRAPPER} -- Integer and natural convertions 129 130 -- This section is currently necessary as Liberty does not have automatic type convertions. 131 integer_to_size_t (an_integer: INTEGER): like size_t 132 -- Comodity feature to cast an integer into an actual size_t 133 external "C inline" 134 alias "((size_t) ($an_integer))" 135 end 136 137end -- class WRAPPER