[Xen-cim] Fw: [Sblim-devel] new CMPILIFY changes commited to CVS

[Gareth S Bestor <bestor@xxxxxxxxxx>]

----- Forwarded by Gareth
S Bestor/Beaverton/IBM on 07/03/2007 09:51 AM -----

Gareth S Bestor/Beaverton/IBM@IBMUS
Sent by: sblim-devel-bounces@xxxxxxxxxxxxxxxxxxxxx

07/02/2007 11:07 PM

To	sblim-devel@xxxxxxxxxxxxxxxxxxxxx
cc
Subject	[Sblim-devel] new CMPILIFY changes commited to CVS

FYI - that I've just committed a bunch of new stuff to CMPILIFY, including
a slightly updated instance provider API, new read-only/single instance
provider, and new association provider, and a bunch more sample providers
to go with them. I've also going to start keeping the SBLIM cvs tree current
with any future additions, rather than posting src code to the mailing
list.  I'll drop a note here anytime there's anything significant
to pull down. 

Latest (final?) default instance provider:

The new instance provider API looks pretty much the same, but a few changes
to note and update your providers with: 

typedef struct { 
   CMPIrc (*load)(); 
   CMPIrc (*unload)(const int terminating); 
   CMPIrc (*begin)(void** enm, const char** properties);
   void (*end)(void* enm); 
   CMPIrc (*getnext)(void* enm, void** inst, const char** properties);
   CMPIrc (*get)(const void* id, void** inst, const char** properties);
   void (*release)(void* inst); 
   CMPIrc (*add)(const void* id, const void* inst);
   CMPIrc (*delete)(const void* id); 
   CMPIrc (*modify)(const void* id, const void* inst, const char**
properties); 
   CMPIrc (*setproperties)(CMPIInstance* instance, const void* inst,
                    
      const char** properties); 
   CMPIrc (*extract)(void** inst, const CMPIInstance* instance,
                    
const char** properties); 
   CMPIrc (*extractid)(void** id, const CMPIInstance* instance);
   void (*releaseid)(void* id); 
} CMPILIFYInstanceMIFT; 


Major diffs:
       - added a few consts to things that shouldn't be
modified 
        - removed return code for things that really
don't need to return anything... [good idea Bas! :-)]
        - renamed the translate functions to be more
meaningful. ie you now "extract" the instance data from the CMPIInstance
        - renamed params names to be less obscure (I
never really likes "res"...) 

There are two sample providers that use this: CMPILIFY_Process and CMPILIFY_ComputerSystem;
that latter being an example of how you could use the enumerated provider
structure for a non-enumerated class. 


Optimized instance provider: 

I also added a new flavor of CMPILIFY instance provider for read-only/single
instance CIM classes. You can select this for your provider simply by using
its respective macro stub CMPILIFYInstance1ROMIStub() ["1RO"
is abbrev for 1 instance, read-only...]. The CMPILIFY API that your provider
must implement for this is much simpler that for the above regular enumerated
instance provider. It consists of: 

typedef struct { 
   CMPIrc (*load)(); 
   CMPIrc (*unload)(const int terminating); 
   CMPIrc (*get)(void** inst, const char** properties);
   void (*release)(void* inst); 
   CMPIrc (*setproperties)(CMPIInstance* instance, const void* inst,
                    
      const char** properties); 
} CMPILIFYInstance1ROMIFT; 


In particular, not need for the instance id, and the write functions (add,
delete, modify) are no longer present. There are two new sample providers
that use this: CMPILIFY_1RO_OperatingSystem and CMILIFY_1RO_ComputerSystem.
the latter implements the exact same CIM class as the other, but this time
using the optimized CMPILIFY provider. Its probably worth comparing the
two source files CMPILIFY_ComputerSystem.c from each to see exactly what
the difference is and what the optimized provider saves you.


Association (and association instance) provider:

I've finished the default CMPILIFY association provider (more 'optimized'
flavors to come later...). This basically reduces your association provider
to implementing two functions: one to return the correct ExecQuery() string
to fetch the right-hand-side (RHS) instances of an association given a
left-hand-side (LHS) instance, and another function to do the same in the
opposite direction. 

typedef struct { 
   CMPIrc (*load)(); 
   CMPIrc (*unload)(const int terminating); 
   CMPIrc (*getlhsquery)(const CMPIInstance* rhsinstance, char** query,
                    
    char** lang); 
   CMPIrc (*getrhsquery)(const CMPIInstance* lhsinstance, char** query,
                    
    char** lang); 
} CMPILIFYAssociationMIFT; 

Please take a look at the two sample association providers the exploit
this - CMPILIFYOSProcess (CIMPLIFY_OperatingSystem<-->CMPILIFY_Process)
and CMPILIFY_RunningOS (CMPILIFY_ComputerSystem<-->CMPILIFY_OperatingSystem).
The first simply generates a query to fetch *all* the instances of the
other association endpoint, since all processes are association to the
(one) operating system. The latter performs a more selective fetch based
on a key property of both endpoint having the same value (ComputerSystem.Name
vs OperatingSystem.CSName). Although this is really just a 1:1 association,
and you could just as easily fetch all (one) instances of either endpoint
class, I wanted to give an example of how to generate a selective filter
based on the properties of the input reference object. In order to have
maximum flexibility in generating the custom filters, the CIM layer fetches
the whole input reference instance first and passes it down to your two
functions - this is in case one of the important properties you need to
correlate on happens to not be a key (!). 

The association provider likewise has its own macro stub CMPILIFYAssociationMIStub().
 Please note all association class info that you need to specify when
invoking the macro (you get it from the asosc class mof). If/when the CMPI
Spec supports class upcalls all this data could be determined at runtime,
but for now it has to be specified explicitly in the macro, to be stashed
away in the MI... 

The CMPILIFYAssociationMIStub() marco also setups an *instance* provider
for your association class [IMPORTANT: so remember to add "instance"
to your reg file!!!] allowing you to run some instance operations on the
association class. Although this is rarely done in practice, some CIMOM
require all classes - instance or otherwise - to implement the instance
intrinsics. For our purposes, only the EnumInstances() and EnumInstnaceNames()
instrinsics are supported for assoc classes, the rest of the instance intrinsics
in the CMPILIFY shared lib will return NOT SUPPORTED. If you are interested,
enumerating *all* the associations between *all* endpoints is accomplished
in the CIM layer by (1) enumerating all the instances of the LHS class,
and for each one returning all its references/referencenames. Note - there
seems to be a bug in sfcb whereby the CBReferences() and CBReferenceNames()
upcalls always return an empty enumeration, hence right now if you run
this under sfcb an enum/enumnames request against the assoc class will
return nothing... 
  


In case you are wondering, I did also  largely implement a flavor
of the (enumerated) instance provider to use embedded C contexts to get
rid of passing (void*) up and down. However, after re-implementing a couple
sample providers against this, both Jim and I independently came to the
conclusion that being forced to create structs for everything, putting
in struct tags, recovering the structs from the tags using container_of(),
... just ended up being a lot more messy and awkward than simply being
able to pass up a pointer to, say, an existing low-level library data structure.
If there is a compelling interest in being able to write CMPILIFY providers
without any (void*)s I can put together a new 'flavor' and add it in, but
after using it myself I really think most folks wont like the extra work
involved and just go back to using the simpler (void*) approach. But please
let me know. 


If you have a made a local copy of the CMPILIFY I strongly recommend saving
it off to the side and re-extracting everything from scratch (eg I put
all the sample providers in their own subdir). 

Method provider and indication provider to follow in a bit...

As always, comments, suggestions, criticism, or praise welcome :-)

- Gareth

Dr. Gareth S. Bestor
IBM Linux Technology Center
M/S DES2-01
15300 SW Koll Parkway, Beaverton, OR 97006
503-578-3186, T/L 775-3186, Fax 503-578-3186 -------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/_______________________________________________
Sblim-devel mailing list
Sblim-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.sourceforge.net/lists/listinfo/sblim-devel
_______________________________________________
Xen-cim mailing list
Xen-cim@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-cim