/src/wrappers/common/library/wrapper.e

  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