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