mono/metadata/external-only.c

   1 /**
   2  * Functions that are in the (historical) embedding API
   3  * but must not be used by the runtime. Often
   4  * just a thin wrapper mono_foo => mono_foo_internal.
   5  *
   6  * Copyright 2018 Microsoft
   7  * Licensed under the MIT license. See LICENSE file in the project root for full license information.
   8  */
   9
  10 // FIXME In order to confirm this is all extern_only,
  11 // a variant of the runtime should be linked without it.
  12
  13 #include "config.h"
  14 #include "class-internals.h"
  15 #include "domain-internals.h"
  16 #include "mono-hash-internals.h"
  17 #include "mono-config-internals.h"
  18 #include "object-internals.h"
  19 #include "class-init.h"
  20 #include "marshal.h"
  21 #include "object.h"
  22 #include "assembly-internals.h"
  23 #include "external-only.h"
  24
  25 /**
  26  * mono_gchandle_new:
  27  * \param obj managed object to get a handle for
  28  * \param pinned whether the object should be pinned
  29  * This returns a handle that wraps the object, this is used to keep a
  30  * reference to a managed object from the unmanaged world and preventing the
  31  * object from being disposed.
  32  *
  33  * If \p pinned is false the address of the object can not be obtained, if it is
  34  * true the address of the object can be obtained.  This will also pin the
  35  * object so it will not be possible by a moving garbage collector to move the
  36  * object.
  37  *
  38  * \returns a handle that can be used to access the object from unmanaged code.
  39  */
  40 uint32_t
  41 mono_gchandle_new (MonoObject *obj, mono_bool pinned)
  42 {
  43         MONO_EXTERNAL_ONLY_GC_UNSAFE (uint32_t, mono_gchandle_new_internal (obj, pinned));
  44 }
  45
  46 /**
  47  * mono_gchandle_new_weakref:
  48  * \param obj managed object to get a handle for
  49  * \param track_resurrection Determines how long to track the object, if this is set to TRUE, the object is tracked after finalization, if FALSE, the object is only tracked up until the point of finalization.
  50  *
  51  * This returns a weak handle that wraps the object, this is used to
  52  * keep a reference to a managed object from the unmanaged world.
  53  * Unlike the \c mono_gchandle_new_internal the object can be reclaimed by the
  54  * garbage collector.  In this case the value of the GCHandle will be
  55  * set to zero.
  56  *
  57  * If \p track_resurrection is TRUE the object will be tracked through
  58  * finalization and if the object is resurrected during the execution
  59  * of the finalizer, then the returned weakref will continue to hold
  60  * a reference to the object.   If \p track_resurrection is FALSE, then
  61  * the weak reference's target will become NULL as soon as the object
  62  * is passed on to the finalizer.
  63  *
  64  * \returns a handle that can be used to access the object from
  65  * unmanaged code.
  66  */
  67 uint32_t
  68 mono_gchandle_new_weakref (MonoObject *obj, mono_bool track_resurrection)
  69 {
  70         MONO_EXTERNAL_ONLY_GC_UNSAFE (uint32_t, mono_gchandle_new_weakref_internal (obj, track_resurrection));
  71 }
  72
  73 /**
  74  * mono_gchandle_get_target:
  75  * \param gchandle a GCHandle's handle.
  76  *
  77  * The handle was previously created by calling \c mono_gchandle_new or
  78  * \c mono_gchandle_new_weakref.
  79  *
  80  * \returns a pointer to the \c MonoObject* represented by the handle or
  81  * NULL for a collected object if using a weakref handle.
  82  */
  83 MonoObject*
  84 mono_gchandle_get_target (uint32_t gchandle)
  85 {
  86         MONO_EXTERNAL_ONLY_GC_UNSAFE (MonoObject*, mono_gchandle_get_target_internal (gchandle));
  87 }
  88
  89 /**
  90  * mono_gchandle_free:
  91  * \param gchandle a GCHandle's handle.
  92  *
  93  * Frees the \p gchandle handle.  If there are no outstanding
  94  * references, the garbage collector can reclaim the memory of the
  95  * object wrapped.
  96  */
  97 void
  98 mono_gchandle_free (uint32_t gchandle)
  99 {
 100         /* Xamarin.Mac and Xamarin.iOS can call this from a worker thread
 101          * that's not attached to the runtime. This is okay for SGen because
 102          * the gchandle code is lockfree.  SGen calls back into Mono which
 103          * fires a profiler event, so the profiler must be prepared to be
 104          * called from threads that aren't attached to Mono. */
 105         MONO_EXTERNAL_ONLY_VOID (mono_gchandle_free_internal (gchandle));
 106 }
 107
 108 /* GC write barriers support */
 109
 110 /**
 111  * mono_gc_wbarrier_set_field:
 112  * \param obj object containing the destination field
 113  * \param field_ptr address of field inside the object
 114  * \param value reference to the object to be stored
 115  * Stores an object reference inside another object, executing a write barrier
 116  * if needed.
 117  */
 118 void
 119 mono_gc_wbarrier_set_field (MonoObject *obj, void* field_ptr, MonoObject* value)
 120 {
 121         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_set_field_internal (obj, field_ptr, value));
 122 }
 123
 124 /**
 125  * mono_gc_wbarrier_set_arrayref:
 126  * \param arr array containing the destination slot
 127  * \param slot_ptr address of slot inside the array
 128  * \param value reference to the object to be stored
 129  * Stores an object reference inside an array of objects, executing a write
 130  * barrier if needed.
 131  */
 132 void
 133 mono_gc_wbarrier_set_arrayref (MonoArray *arr, void* slot_ptr, MonoObject* value)
 134 {
 135         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_set_arrayref_internal (arr, slot_ptr, value));
 136 }
 137
 138 /**
 139  * mono_gc_wbarrier_arrayref_copy:
 140  * \param dest_ptr destination slot address
 141  * \param src_ptr source slot address
 142  * \param count number of references to copy
 143  * Copies \p count references from one array to another, executing a write
 144  * barrier if needed.
 145  */
 146 void
 147 mono_gc_wbarrier_arrayref_copy (void* dest_ptr, /*const*/ void* src_ptr, int count)
 148 {
 149         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_arrayref_copy_internal (dest_ptr, src_ptr, count));
 150 }
 151
 152 /**
 153  * mono_gc_wbarrier_generic_store:
 154  * \param ptr address of field
 155  * \param obj object to store
 156  * Stores the \p value object inside the field represented by \p ptr,
 157  * executing a write barrier if needed.
 158  */
 159 void
 160 mono_gc_wbarrier_generic_store (void* ptr, MonoObject* value)
 161 {
 162         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_generic_store_internal (ptr, value));
 163 }
 164
 165 /**
 166  * mono_gc_wbarrier_generic_store_atomic:
 167  * Same as \c mono_gc_wbarrier_generic_store but performs the store
 168  * as an atomic operation with release semantics.
 169  */
 170 void
 171 mono_gc_wbarrier_generic_store_atomic (void *ptr, MonoObject *value)
 172 {
 173         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_generic_store_atomic_internal (ptr, value));
 174 }
 175
 176 /**
 177  * mono_gc_wbarrier_generic_nostore:
 178  * Executes a write barrier for an address, informing the GC that
 179  * the reference stored at that address has been changed.
 180  */
 181 void
 182 mono_gc_wbarrier_generic_nostore (void* ptr)
 183 {
 184         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_generic_nostore_internal (ptr));
 185 }
 186
 187 /**
 188  * mono_gc_wbarrier_object_copy:
 189  * \param dest destination address
 190  * \param src source address
 191  * \param count number of elements to copy
 192  * \param klass type of elements to copy
 193  * Copies \p count elements of type \p klass from \p src address to
 194  * \dest address, executing any necessary write barriers.
 195  */
 196 void
 197 mono_gc_wbarrier_value_copy (void* dest, /*const*/ void* src, int count, MonoClass *klass)
 198 {
 199         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_value_copy_internal (dest, src, count, klass));
 200 }
 201
 202 /**
 203  * mono_gc_wbarrier_object_copy:
 204  * \param obj destination object
 205  * \param src source object
 206  * Copies contents of \p src to \p obj, executing any necessary write
 207  * barriers.
 208  */
 209 void
 210 mono_gc_wbarrier_object_copy (MonoObject* obj, MonoObject *src)
 211 {
 212         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_gc_wbarrier_object_copy_internal (obj, src));
 213 }
 214
 215 /**
 216  * mono_class_init:
 217  * \param klass the class to initialize
 218  *
 219  * Compute the \c instance_size, \c class_size and other infos that cannot be
 220  * computed at \c mono_class_get time. Also compute vtable_size if possible.
 221  * Initializes the following fields in \p klass:
 222  * - all the fields initialized by \c mono_class_init_sizes
 223  * - has_cctor
 224  * - ghcimpl
 225  * - inited
 226  *
 227  * LOCKING: Acquires the loader lock.
 228  *
 229  * \returns TRUE on success or FALSE if there was a problem in loading
 230  * the type (incorrect assemblies, missing assemblies, methods, etc).
 231  */
 232 mono_bool
 233 mono_class_init (MonoClass *klass)
 234 {
 235         MONO_EXTERNAL_ONLY_GC_UNSAFE (gboolean, mono_class_init_internal (klass));
 236 }
 237
 238 /**
 239  * mono_g_hash_table_new_type:
 240  */
 241 MonoGHashTable*
 242 mono_g_hash_table_new_type (GHashFunc hash_func, GEqualFunc key_equal_func, MonoGHashGCType type, MonoGCRootSource source, void *key, const char *msg)
 243 {
 244         MONO_EXTERNAL_ONLY_GC_UNSAFE (MonoGHashTable*, mono_g_hash_table_new_type_internal (hash_func, key_equal_func, type, source, key, msg));
 245 }
 246
 247 /**
 248  * mono_config_for_assembly:
 249  */
 250 void
 251 mono_config_for_assembly (MonoImage *assembly)
 252 {
 253         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_config_for_assembly_internal (assembly));
 254 }
 255
 256 /**
 257  * mono_class_get_property_from_name:
 258  * \param klass a class
 259  * \param name name of the property to lookup in the specified class
 260  *
 261  * Use this method to lookup a property in a class
 262  * \returns the \c MonoProperty with the given name, or NULL if the property
 263  * does not exist on the \p klass.
 264  */
 265 MonoProperty*
 266 mono_class_get_property_from_name (MonoClass *klass, const char *name)
 267 {
 268         MONO_EXTERNAL_ONLY_GC_UNSAFE (MonoProperty*, mono_class_get_property_from_name_internal (klass, name));
 269 }
 270
 271 /**
 272  * mono_class_is_subclass_of:
 273  * \param klass class to probe if it is a subclass of another one
 274  * \param klassc the class we suspect is the base class
 275  * \param check_interfaces whether we should perform interface checks
 276  *
 277  * This method determines whether \p klass is a subclass of \p klassc.
 278  *
 279  * If the \p check_interfaces flag is set, then if \p klassc is an interface
 280  * this method return TRUE if the \p klass implements the interface or
 281  * if \p klass is an interface, if one of its base classes is \p klass.
 282  *
 283  * If \p check_interfaces is false, then if \p klass is not an interface,
 284  * it returns TRUE if the \p klass is a subclass of \p klassc.
 285  *
 286  * if \p klass is an interface and \p klassc is \c System.Object, then this function
 287  * returns TRUE.
 288  *
 289  */
 290 gboolean
 291 mono_class_is_subclass_of (MonoClass *klass, MonoClass *klassc, gboolean check_interfaces)
 292 {
 293         MONO_EXTERNAL_ONLY_GC_UNSAFE (gboolean, mono_class_is_subclass_of_internal (klass, klassc, check_interfaces));
 294 }
 295
 296 /**
 297  * mono_domain_set_internal:
 298  * \param domain the new domain
 299  *
 300  * Sets the current domain to \p domain.
 301  */
 302 void
 303 mono_domain_set_internal (MonoDomain *domain)
 304 {
 305         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_domain_set_internal_with_options (domain, TRUE));
 306 }
 307
 308 /**
 309  * mono_domain_set:
 310  * \param domain domain
 311  * \param force force setting.
 312  *
 313  * Set the current appdomain to \p domain. If \p force is set, set it even
 314  * if it is being unloaded.
 315  *
 316  * \returns TRUE on success; FALSE if the domain is unloaded
 317  */
 318 gboolean
 319 mono_domain_set (MonoDomain *domain, gboolean force)
 320 {
 321         if (!force && domain->state == MONO_APPDOMAIN_UNLOADED)
 322                 return FALSE;
 323
 324         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_domain_set_internal_with_options (domain, TRUE));
 325         return TRUE;
 326 }
 327
 328 /**
 329  * mono_assembly_name_free:
 330  * \param aname assembly name to free
 331  *
 332  * Frees the provided assembly name object.
 333  * (it does not frees the object itself, only the name members).
 334  */
 335 void
 336 mono_assembly_name_free (MonoAssemblyName *aname)
 337 {
 338         if (!aname)
 339                 return;
 340         MONO_EXTERNAL_ONLY_GC_UNSAFE_VOID (mono_assembly_name_free_internal (aname));
 341 }