TechTalk Genome v4.2

Context.Pin<T> Method (T)

Creates proxy to obj that is bound to this Context.

public T Pin<T>(
   T obj


A proxy specifying a persistent object that is valid in this Context.

Return Value

If obj is an unbound proxy or a proxy bound to another Context a proxy bound to this Context is created for the persistent object specified by obj and returned; if obj is a proxy already bound to this Context then obj is returned; a null reference is returned if obj is a null reference.




The Context class encapsulates a data access session to all DataDomains in the calling AppDomain. All modifications to persistent data are routed trough the active Context that governs the operation.

When a persistent object is accessed by the application, a stateless proxy to the object is returned only. The proxy serves as a handle to the state of the object that is being kept in one or more Contexts. When the caller calls methods or accesses properties of a persistent object, the active Context is used to retrieve state data, thus allowing different blocks of the application to be isolated in how they see the persistent state. The active Context is determined using different strategies, based on the proxy type.

Proxies returned by Genome are context independent, that is they do not have any Context preference. Whenever data is accessed on an unbound proxy, the context stack of the calling thread is investigated to acquire the active context as returned by Current. Thus the Context used by unbound proxies solely depends on the previous Push method calls in the same thread. Since context independent proxies are not bound to any context, they are valid even if the active Context in the calling thread is discarded - although the proxy might access different state of the same object when applied in a different Context.

Context-bound proxies are made explicitly bound to their active Context using the Pin<S> method. Whenever data is accessed on a context-bound proxy the active Context in the calling thread is ignored and the referred Context is used. Whenever a method call is made on a context-bound proxy, the referred Context is made active in the calling thread temporarily for the time of the call.

As opposed to unbound proxies, context bound proxies become invalid if their active Context is discarded. If the caller attempts to access object state or call methods on a bound proxy if its active Context has been already disposed, Genome throws a GenomeException. In this case, the caller can use Unpin<S> to regain a context-free proxy to the object, or Pin<S> to gain a proxy bound to a valid context for the same object.


Exception TypeCondition
GenomeExceptionobj is not a persistent object.


Context ctx = LocalContext.Create();
using(Context.Push(ctx, true))
    Person obj1 = (Person)DataDomain1.Extent(typeof(Person))["Name=={0}", "Adam"].ToObject();
    Console.WriteLine(obj1.Name);           // 'ctx' is used to retrieve the state of 'Adam'
    Person obj2 = (Person)ctx.Pin(obj1);
    Console.WriteLine(obj2.Name);           // 'ctx' is used to retrieve the state of 'Adam'
    Context nestedCtx = LocalContext.Create();
    using(Context.Push(nestecCtx, true))
        Console.WriteLine(obj1.Name);       // 'nestedCtx' is used to retrieve the state of 'Adam'
        Console.WriteLine(obj2.Name);       // 'ctx' is used to retrieve the state of 'Adam'
// 'ctx' is disposed and is not valid anymore

Console.WriteLine(obj1.Name);               // the global application context is used to retrieve the state of 'Adam'
Console.WriteLine(obj2.Name);               // error: 'ctx' is already disposed!

Person obj3 = (Person)Context.Unpin(obj2);
Console.WriteLine(obj1==obj3);              // true



Namespace: TechTalk.Genome

Assembly: TechTalk.Genome (in TechTalk.Genome.dll)


Editions: Professional, Evaluation, Express

See Also

Context Class | TechTalk.Genome Namespace | Context.Pin<T> Overload List | Unpin<S> | CtxMgmtGuide.Chapter5