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?
Missing Obtain() & Release() autodocs
Missing Obtain() & Release() autodocs
AmigaOne X1000 with 2GB memory - OS4.1 FE
- broadblues
- AmigaOS Core Developer
- Posts: 600
- Joined: Sat Jun 18, 2011 2:40 am
- Location: Portsmouth, UK
- Contact:
Re: Missing Obtain() & Release() autodocs
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:
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?
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:
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!
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().
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?
Re: Missing Obtain() & Release() autodocs
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.Was there specific reason why you were investigationg them?
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.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.
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