1// Licensed to the .NET Foundation under one or more agreements.
2// The .NET Foundation licenses this file to you under the MIT license.
3// See the LICENSE file in the project root for more information.
4//
5// File: COMDependentHandle.h
6//
7
8//
9// FCall's for the DependentHandle class
10//
11
12
13#ifndef __COMDEPENDENTHANDLE_H__
14#define __COMDEPENDENTHANDLE_H__
15
16#include "fcall.h"
17
18// A dependent handle is conceputally a tuple containing two object reference
19//
20// * A Primary object (think key)
21// * A Secondary Object (think value)
22//
23// The reference to both the primary object is (long) weak (will not keep the object alive). However the
24// reference to the secondary object is (long) weak if the primary object is dead, and strong if the primary
25// object is alive. (Hence it is a 'Dependent' handle since the strength of the secondary reference depends
26// on the primary).
27//
28// The effect of this semantics is that it seems that while the DependentHandle exists, the system behaves as
29// if there was a normal strong reference from the primary object to the secondary one.
30//
31// The usefulness of a DependentHandle is to allow other objects to be 'attached' to a given object. By
32// having a hash table where the entries are dependent handles you can attach arbitrary objects to another
33// object.
34//
35// If you attmpted to do this with an ordinary table if the value would have to be a strong reference, which
36// if it points back to the key, will form a loop that the GC will not be able to break DependentHandle is
37// effecively a way of informing the GC about the dedendent relationsship between the key and the value so
38// such cycles can be broken.
39//
40// Almost all the interesting for DependentHandle is in code:Ref_ScanDependentHandles
41class DependentHandle
42{
43public:
44 static FCDECL2(OBJECTHANDLE, nInitialize, Object *primary, Object *secondary);
45 static FCDECL1(Object *, nGetPrimary, OBJECTHANDLE handle);
46 static FCDECL2(Object *, nGetPrimaryAndSecondary, OBJECTHANDLE handle, Object **outSecondary);
47 static FCDECL1(VOID, nFree, OBJECTHANDLE handle);
48 static FCDECL2(VOID, nSetPrimary, OBJECTHANDLE handle, Object *primary);
49 static FCDECL2(VOID, nSetSecondary, OBJECTHANDLE handle, Object *secondary);
50};
51
52#endif
53
54