OLD | NEW |
1 /* | 1 /* |
2 * Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 2 * Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
3 * for details. All rights reserved. Use of this source code is governed by a | 3 * for details. All rights reserved. Use of this source code is governed by a |
4 * BSD-style license that can be found in the LICENSE file. | 4 * BSD-style license that can be found in the LICENSE file. |
5 */ | 5 */ |
6 | 6 |
7 #ifndef INCLUDE_DART_API_H_ | 7 #ifndef INCLUDE_DART_API_H_ |
8 #define INCLUDE_DART_API_H_ | 8 #define INCLUDE_DART_API_H_ |
9 | 9 |
10 /** \mainpage Dart Embedding API Reference | 10 /** \mainpage Dart Embedding API Reference |
(...skipping 483 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
494 DART_EXPORT Dart_WeakPersistentHandle Dart_NewWeakPersistentHandle( | 494 DART_EXPORT Dart_WeakPersistentHandle Dart_NewWeakPersistentHandle( |
495 Dart_Handle object, | 495 Dart_Handle object, |
496 void* peer, | 496 void* peer, |
497 intptr_t external_allocation_size, | 497 intptr_t external_allocation_size, |
498 Dart_WeakPersistentHandleFinalizer callback); | 498 Dart_WeakPersistentHandleFinalizer callback); |
499 | 499 |
500 DART_EXPORT void Dart_DeleteWeakPersistentHandle( | 500 DART_EXPORT void Dart_DeleteWeakPersistentHandle( |
501 Dart_Isolate isolate, | 501 Dart_Isolate isolate, |
502 Dart_WeakPersistentHandle object); | 502 Dart_WeakPersistentHandle object); |
503 | 503 |
504 /** | |
505 * Allocates a prologue weak persistent handle for an object. | |
506 * | |
507 * Prologue weak persistent handles are similar to weak persistent | |
508 * handles but exhibit different behavior during garbage collections | |
509 * that invoke the prologue and epilogue callbacks. While weak | |
510 * persistent handles always weakly reference their referents, | |
511 * prologue weak persistent handles weakly reference their referents | |
512 * only during a garbage collection that invokes the prologue and | |
513 * epilogue callbacks. During all other garbage collections, prologue | |
514 * weak persistent handles strongly reference their referents. | |
515 * | |
516 * This handle has the lifetime of the current isolate unless the object | |
517 * pointed to by the handle is garbage collected, in this case the VM | |
518 * automatically deletes the handle after invoking the callback associated | |
519 * with the handle. The handle can also be explicitly deallocated by | |
520 * calling Dart_DeleteWeakPersistentHandle. | |
521 * | |
522 * If the object becomes unreachable the callback is invoked with the weak | |
523 * persistent handle and the peer as arguments. This gives the native code the | |
524 * ability to cleanup data associated with the object and clear out any cached | |
525 * references to the handle. All references to this handle after the callback | |
526 * will be invalid. It is illegal to call into the VM from the callback. | |
527 * If the handle is deleted before the object becomes unreachable, | |
528 * the callback is never invoked. | |
529 * | |
530 * Requires there to be a current isolate. | |
531 * | |
532 * \param object An object. | |
533 * \param peer A pointer to a native object or NULL. This value is | |
534 * provided to callback when it is invoked. | |
535 * \param external_allocation_size The number of externally allocated | |
536 * bytes for peer. Used to inform the garbage collector. | |
537 * \param callback A function pointer that will be invoked sometime | |
538 * after the object is garbage collected, unless the handle has been deleted. | |
539 * A valid callback needs to be specified it cannot be NULL. | |
540 * | |
541 * \return Success if the prologue weak persistent handle was created. | |
542 * Otherwise, returns an error. | |
543 */ | |
544 DART_EXPORT Dart_WeakPersistentHandle Dart_NewPrologueWeakPersistentHandle( | |
545 Dart_Handle object, | |
546 void* peer, | |
547 intptr_t external_allocation_size, | |
548 Dart_WeakPersistentHandleFinalizer callback); | |
549 | |
550 /** | |
551 * Is this object a prologue weak persistent handle? | |
552 * | |
553 * Requires there to be a current isolate. | |
554 */ | |
555 DART_EXPORT bool Dart_IsPrologueWeakPersistentHandle( | |
556 Dart_WeakPersistentHandle object); | |
557 | |
558 typedef struct _Dart_WeakReferenceSetBuilder* Dart_WeakReferenceSetBuilder; | |
559 typedef struct _Dart_WeakReferenceSet* Dart_WeakReferenceSet; | |
560 | |
561 /** | |
562 * Constructs a weak references set builder. | |
563 * | |
564 * \returns a pointer to the weak reference set builder if successful. | |
565 * Otherwise, returns NULL. | |
566 */ | |
567 DART_EXPORT Dart_WeakReferenceSetBuilder Dart_NewWeakReferenceSetBuilder(); | |
568 | |
569 /** | |
570 * Constructs a set of weak references from the Cartesian product of | |
571 * the objects in the key set and the objects in values set. | |
572 * | |
573 * \param set_builder The weak references set builder which was created | |
574 * using Dart_NewWeakReferenceSetBuilder(). | |
575 * \param key An object reference. This references will be | |
576 * considered weak by the garbage collector. | |
577 * \param value An object reference. This reference will be | |
578 * considered weak by garbage collector unless any object reference | |
579 * in 'keys' is found to be strong. | |
580 * | |
581 * \return a pointer to the weak reference set if successful. | |
582 * Otherwise, returns NULL. | |
583 */ | |
584 DART_EXPORT Dart_WeakReferenceSet Dart_NewWeakReferenceSet( | |
585 Dart_WeakReferenceSetBuilder set_builder, | |
586 Dart_WeakPersistentHandle key, | |
587 Dart_WeakPersistentHandle value); | |
588 | |
589 /** | |
590 * Append the pair of key/value object references to the weak references set. | |
591 * | |
592 * \param reference_set A weak references set into which the pair of key/value | |
593 * needs to be added. | |
594 * \param key An object reference. This references will be | |
595 * considered weak by the garbage collector. | |
596 * \param value An object reference. This reference will be | |
597 * considered weak by garbage collector unless any object reference | |
598 * in 'keys' is found to be strong. | |
599 * | |
600 * \return Success if the prologue weak persistent handle was created. | |
601 * Otherwise, returns an error. | |
602 */ | |
603 DART_EXPORT Dart_Handle Dart_AppendToWeakReferenceSet( | |
604 Dart_WeakReferenceSet reference_set, | |
605 Dart_WeakPersistentHandle key, | |
606 Dart_WeakPersistentHandle value); | |
607 | |
608 /** | |
609 * Append the key object reference to the weak references set. | |
610 * | |
611 * \param reference_set A weak references set into which the key | |
612 * needs to be added. | |
613 * \param key An object reference. This references will be | |
614 * considered weak by the garbage collector. | |
615 * | |
616 * \return Success if the prologue weak persistent handle was created. | |
617 * Otherwise, returns an error. | |
618 */ | |
619 DART_EXPORT Dart_Handle Dart_AppendKeyToWeakReferenceSet( | |
620 Dart_WeakReferenceSet reference_set, | |
621 Dart_WeakPersistentHandle key); | |
622 | |
623 /** | |
624 * Append the value object reference to the weak references set. | |
625 * | |
626 * \param reference_set A weak references set into which the key | |
627 * needs to be added. | |
628 * \param value An object reference. This references will be | |
629 * considered weak by the garbage collector. | |
630 * | |
631 * \return Success if the prologue weak persistent handle was created. | |
632 * Otherwise, returns an error. | |
633 */ | |
634 DART_EXPORT Dart_Handle Dart_AppendValueToWeakReferenceSet( | |
635 Dart_WeakReferenceSet reference_set, | |
636 Dart_WeakPersistentHandle value); | |
637 | |
638 | 504 |
639 /* | 505 /* |
640 * ============================ | 506 * ============================ |
641 * Garbage Collection Callbacks | 507 * Garbage Collection Callbacks |
642 * ============================ | 508 * ============================ |
643 */ | 509 */ |
644 | 510 |
645 /** | 511 /** |
646 * Callbacks signal the beginning and end of a garbage collection. | 512 * Callbacks signal the beginning and end of a garbage collection. |
647 * | 513 * |
(...skipping 2315 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2963 | 2829 |
2964 DART_EXPORT Dart_Handle Dart_CreatePrecompiledSnapshot( | 2830 DART_EXPORT Dart_Handle Dart_CreatePrecompiledSnapshot( |
2965 uint8_t** vm_isolate_snapshot_buffer, | 2831 uint8_t** vm_isolate_snapshot_buffer, |
2966 intptr_t* vm_isolate_snapshot_size, | 2832 intptr_t* vm_isolate_snapshot_size, |
2967 uint8_t** isolate_snapshot_buffer, | 2833 uint8_t** isolate_snapshot_buffer, |
2968 intptr_t* isolate_snapshot_size, | 2834 intptr_t* isolate_snapshot_size, |
2969 uint8_t** instructions_snapshot_buffer, | 2835 uint8_t** instructions_snapshot_buffer, |
2970 intptr_t* instructions_snapshot_size); | 2836 intptr_t* instructions_snapshot_size); |
2971 | 2837 |
2972 #endif /* INCLUDE_DART_API_H_ */ /* NOLINT */ | 2838 #endif /* INCLUDE_DART_API_H_ */ /* NOLINT */ |
OLD | NEW |