+
Point of view
All features
deferred class CACHING_FACTORY [ITEM_ -> WRAPPER]
Summary
top
A factory that retrieves wrappers from a cache, usually a dictionary; used to implement collection of wrapped objects
copyright
Copyright (C) 2006-2022: , 2007 Paolo Redaelli This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Direct parents
Inherit list: WRAPPER_FACTORY
Class invariant
top
Overview
top
Features
{WRAPPER, WRAPPER_HANDLER}
  • wrappers: HASHED_DICTIONARY[ITEM_, POINTER]
    Dictionary cache storing wrappers; usually used in WRAPPER_COLLECTIONs or WRAPPER_DICTIONARY Key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper.
  • wrapper (a_pointer: POINTER): ITEM_
    The wrapper for a_pointer.
Implementation
{WRAPPER, WRAPPER_HANDLER}
  • wrapper_or_void (a_pointer: POINTER): ITEM_
    A wrapper for a_pointer or Void if a_pointer default_pointer (NULL in C).
Utility features
{}
Wrapper related exceptions
{}
Various exceptions codes:
{ANY}
{ANY}
Status report:
{ANY}
Basic operations:
{ANY}
  • die (code: INTEGER_32)
    Terminate execution with exit status code, without triggering an exception.
  • raise (name: STRING)
    Raise a developer exception of name name.
  • throw (a_exception: EXCEPTION)
Non-Standard Extensions:
{ANY}
{}
wrappers: HASHED_DICTIONARY[ITEM_, POINTER]
deferred function
{WRAPPER, WRAPPER_HANDLER}
top
Dictionary cache storing wrappers; usually used in WRAPPER_COLLECTIONs or WRAPPER_DICTIONARY Key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper.
This way you can get back an already-created Eiffel wrapper. Heirs of SHARED_C_STRUCT, i.e. G_OBJECT could provide alternative implementation that will not rely on this dictionary.
wrapper (a_pointer: POINTER): ITEM_
deferred function
{WRAPPER, WRAPPER_HANDLER}
top
The wrapper for a_pointer.
It could be newly created or retrieved from a cache, a dictionary, from the underlying object, depending on the implementation. See also wrapper_or_void: when a_pointer is the default pointer (known as NULL in C) Result will be Void.
require
  • pointer_not_null: a_pointer.is_not_null
ensure
  • wrappers.has(a_pointer)
  • non_void: Result /= Void
  • correct: Result.handle = a_pointer
wrapper_or_void (a_pointer: POINTER): ITEM_
effective function
{WRAPPER, WRAPPER_HANDLER}
top
A wrapper for a_pointer or Void if a_pointer default_pointer (NULL in C).
A commodity feature to replace the following code snippet: my_gobject: A_WRAPPER local p: POINTER do 
  p := get_foo(handle)
  if p.is_not_null then
    Result := factory.wrapper(p)
  end
end
with
my_gobject: A_G_OBJECT_HEIR
  do
    Result := factory.wrapper_or_void(get_foo(handle))
  end
ensure
  • null_pointer_returns_void: a_pointer.is_null implies Result = Void
  • correct: a_pointer.is_not_null implies Result /= Void and then Result.handle = a_pointer
null_or (a_wrapper: WRAPPER): POINTER
effective function
{}
top
The handle of a_wrapper, or the default_pointer if a_wrapper is Void
ensure
  • definition: Result = default_pointer or else a_wrapper /= Void and then Result = a_wrapper.handle
null_or_string (a_string: ABSTRACT_STRING): POINTER
effective function
{}
top
A pointer to a memory area containing the content of a_string or default_pointer if a_string is Void.
The memory area may be the internal buffer of a_string or a newly allocated one.
ensure
  • definition: Result = default_pointer or a_string /= Void implies Result = a_string.to_external
null_or_array (a_collection: WRAPPER_COLLECTION[WRAPPER]): POINTER
effective function
{}
top
A pointer to the contenct of a_collection or NULL (default_pointer) if a_collection is Void
ensure
  • definition: a_collection = Void implies Result.is_null and a_collection /= Void implies Result.is_not_null
collection_to_c_array (a_collection: COLLECTION[WRAPPER]): FAST_ARRAY[POINTER]
effective function
{}
top
An array containing the pointers to the objects wrapped by a_collection wrappers.
TODO: avoid creating a new array whenever possible.
require
  • a_collection /= Void
  • not a_collection.is_empty
pointer_to_unwrapped_deferred_object: STRING
is "A C function returned a pointer to an unwrapped object which is wrapped by a deferred class. It is not possible to create a correct wrapper."
constant attribute
{}
top
retrieved_object_mismatch: STRING
is "Retrieved_object_mismatch: the Eiffel wrapper associated with a pointer is not an actual wrapper for the object referred by that pointer "
constant attribute
{}
top
copying_an_uncopyable: STRING
is "Trying to copy an uncopyable wrapper: such objects are usually shortly lived"
constant attribute
{}
top
Check_instruction: INTEGER_32
is 1
constant attribute
{ANY}
top
Exception code for violated check.
Class_invariant: INTEGER_32
is 2
constant attribute
{ANY}
top
Exception code for violated class invariant.
Developer_exception: INTEGER_32
is 3
constant attribute
{ANY}
top
Exception code for developer exception.
See also: raise, throw
Incorrect_inspect_value: INTEGER_32
is 4
constant attribute
{ANY}
top
Exception code for inspect statement.
This exception occurs when Void is passed as the expression to inspect ("inspect on STRING only). This exception also occurs when the inspected value selects no branch (when the keyword "else" not used, one "when" branch _must_ be selected). Some value which is not one of the inspect constants, if there is no Else_part
Loop_invariant: INTEGER_32
is 5
constant attribute
{ANY}
top
Exception code for violated loop invariant
Loop_variant: INTEGER_32
is 6
constant attribute
{ANY}
top
Exception code for non-decreased loop variant
No_more_memory: INTEGER_32
is 7
constant attribute
{ANY}
top
Exception code for failed memory allocation
Postcondition: INTEGER_32
is 8
constant attribute
{ANY}
top
Exception code for violated postcondition.
Precondition: INTEGER_32
is 9
constant attribute
{ANY}
top
Exception code for violated precondition.
Routine_failure: INTEGER_32
is 10
constant attribute
{ANY}
top
Exception code for failed routine.
Os_signal: INTEGER_32
is 11
constant attribute
{ANY}
top
Exception code for a signal received from the OS.
Void_attached_to_expanded: INTEGER_32
is 12
constant attribute
{ANY}
top
Exception code for attachment of Void value to expanded entity.
Void_call_target: INTEGER_32
is 13
constant attribute
{ANY}
top
Exception code for feature applied to Void reference
System_level_type_error: INTEGER_32
is 14
constant attribute
{ANY}
top
Exception code for the system-level type error (this kind of error mostly arise with covariant redefinition).
exception_name: STRING
effective function
{ANY}
top
name_of_exception (a_exception: INTEGER_32): STRING
effective function
{ANY}
top
developer_exception: EXCEPTION
effective function
{ANY}
top
The last developer-thrown exception.
require
developer_exception_name: STRING
effective function
{ANY}
top
Name of last developer-raised exception.
require
is_developer_exception: BOOLEAN
effective function
{ANY}
top
Is the last exception originally due to a developer exception?
is_developer_named_exception: BOOLEAN
effective function
{ANY}
top
Is the last exception originally due to a developer exception?
is_developer_exception_of_name (name: STRING): BOOLEAN
effective function
{ANY}
top
Is the last exception originally due to a developer exception of name name?
assertion_violation: BOOLEAN
effective function
{ANY}
top
Is last exception originally due to a violated assertion or non-decreasing variant?
exception: INTEGER_32
{ANY}
top
Code of last exception that occurred.
is_signal: BOOLEAN
effective function
{ANY}
top
Is last exception originally due to an external event (operating system signal) ?
die (code: INTEGER_32)
effective procedure
{ANY}
top
Terminate execution with exit status code, without triggering an exception.
raise (name: STRING)
effective procedure
{ANY}
top
Raise a developer exception of name name.
require
  • name /= Void
throw (a_exception: EXCEPTION)
effective procedure
{ANY}
top
require
  • a_exception /= Void
signal_number: INTEGER_32
{ANY}
top
Signal Number received from OS.
 Zero if exception is not an OS signal.
named_exception: NAMED_EXCEPTION
once function
{}
top
developer_exception_memory: REFERENCE[EXCEPTION]
once function
{}
top
raise_exception (code: INTEGER_32)
{}
top