On Sep 1, 2006, at 3:15 PM, Juan RP wrote:

> Do I need to release references with every obj used in the code?

 From the proplib(3) manual page:

      The rules for managing reference counts are very simple:

      o   If you create an object and do not explicitly maintain a  
reference to
          it, you must release it.

      o   If you get a reference to an object from other code and wish  
to main-
          tain a reference to it, you must retain the object.  You are  
respon-
          sible for releasing the object once you drop that reference.

      o   You must never release an object unless you create it or  
retain it.

So, take the following example:

void
foo(device_t dev)
{
	prop_number_t num;

	num = prop_dictionary_get(device_properties(dev),
				  "some-prop");

	/* ... do something ... */
}

You did not need to manipulate the ref count because you did not  
maintain a reference outside the scope of where the device (and thus  
its properties dictionary) was guaranteed to be valid.

However:

void
foo(device_t dev, prop_number_t *nump)
{
	prop_number_t num;

	num = prop_dictionary_get(device_properties(dev),
				  "some-prop");

	prop_object_retain(num);

	*nump = num;
}

...because you are maintaining a reference (via *nump) to that object,  
you must retain it (bump the ref count).

When you add something to a collection (array or dictionary), the  
collection maintains a reference, and thus retains it:

[from prop_array(3)]
      prop_array_add(prop_array_t array, prop_object_t obj)
             Add a reference to the object obj to the array, appending  
to the
             end and growing the array's capacity of necessary.  The  
object
             will be retained by the array.  Returns TRUE if storing  
the object
             was successful and FALSE otherwise.

If you create an object are finished with it after storing it in a  
collection, then you must release it (decr the ref count) because  
object creators must release unless they keep a reference.

> And when the obj is stored in a dictionary or array  its refcount
> is increased, but how can I use it in another code?

All of the objects contained by a collection are valid so long as the  
collection is valid.

> My plan is to construct the array with supported frequencies in the MI
> driver and pass it to sysmon, but I will need to use this array too in
> the userland code.

Passing it to userland code means "externalize" followed by  
"internalize", which is essentially a deep copy, so you don't need to  
worry about it in this case.

>
> Am I right?
>
>> And finally, construct the array BEFORE storing it in the dictionary.
>> That way the "I am done with the array" is more clear, and you also
>> avoid having partially constructed data visible in the dictionary.
>
> Thanks for your comments.

-- thorpej