Missing Obtain() & Release() autodocs

Have a question about our Software Developer Kit? Ask them here.
Post Reply
xenic
Posts: 1185
Joined: Sun Jun 19, 2011 12:06 am

Missing Obtain() & Release() autodocs

Post by xenic »

I was checking the AmigaDOS documentation for CreateNewProv() and noticed the use of IExec->Obtain() and IExec->Release() in the examples. I checked the exec autodoc and there is no mention of those 2 functions. The exec Interface file (Include/include_h/interfaces/exec.h) show a return of ULONG but I can't find any expalnation of what the return value signifies. Could we have autodocs for those functions added to the exec autodoc file? Exactly what is being obtained and released?

The migration guide contains a short explanation and example for Obtain() & Release(). It shows Release() being called inside a sub-task while the AmigaDOS process example shows it being called from the main process after child processes return. Does it matter where the Release() occurs?
AmigaOne X1000 with 2GB memory - OS4.1 FE
User avatar
broadblues
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 600
Joined: Sat Jun 18, 2011 2:40 am
Location: Portsmouth, UK
Contact:

Re: Missing Obtain() & Release() autodocs

Post by broadblues »

Obtain() obtains the interface, Release() releases it. :-)

In general usage you don't call these direct Exec does it for you when you call GetInterface(). Often all they do is increment or decrement a counter, but some libraries do more, setup context info etc.

The CreateNewProc() example shows Obtain() and Release() being call in a program with no clibrary startup code, so the exec interface is got from SysBase by hand, thus you have to Obtain() it.

I'm almost but not quite reasonably sure that Obtain() and Release() need to be called on the same task, and you shouldn't use the interface before call Obtain() or after calling Release().

As almost all user code uses the C library startup 90% of the time you don't need to care about this.

Obtain() and Realease() are documented in the Libraries and Devices.pdf

It says:

If an interface pointer is passed along to another entity, for example another thread, then that entity must call
Obtain() before using the interface. Likewise, when the entity is done, it needs to call Release().
However I supsect this is not needed in the child proc in the CreatenewProc() example because it is a Child and so is not going to outlive it's parent. Either that ot the example is wrong in that respect!


The example in the Migration guide is different. It Obtains() the interface before the task as I suppose the task is to be asynchronously and the main program isn't going to wait. So is avoiding race condition.

I'm not sure very much software uses interfaces in the way object orientated data way the example in Migration guide shows.

Was there specific reason why you were investigationg them?
xenic
Posts: 1185
Joined: Sun Jun 19, 2011 12:06 am

Re: Missing Obtain() & Release() autodocs

Post by xenic »

Was there specific reason why you were investigationg them?
I was going to use CreateNewProc() to open an asynchronous requester until further investigation revealed that it was much simpler to open the async requester from a task. In the case of a task it appears to be OK to share the AmigaDOS Interface between the main program and a task. I wasn't sure if the same was true for processes which is why I was reading the AmigaDOS CreateNewProc() examples.
The CreateNewProc() example shows Obtain() and Release() being call in a program with no clibrary startup code, so the exec interface is got from SysBase by hand, thus you have to Obtain() it.
O.K. Apparently the Obtain() in the AmigaDOS examples has nothing to do with starting a process but is (as you say) only necessary because the examples have no c library startup code.

It certainly wouldn't hurt to add Obtain() & Release() to the exec autodocs so we don't have to go hunting through the PDF docs for such information.
AmigaOne X1000 with 2GB memory - OS4.1 FE
Post Reply