Missing Obtain() & Release() autodocs

[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?

[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]

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.