src/platform/generic/dl.c: codingstd failure not easily fixed

[James E Keenan]

We are currently experiencing failures in coding standards in 
src/platform/generic/dl.c.  The failures are in c_arg_assert.t and 
c_function_docs.t.

These are the failures in c_arg_assert.t:

#####
  $ prove -v t/codingstd/c_arg_assert.t
t/codingstd/c_arg_assert.t ..
1..2
# finding macro definitions and invocations
not ok 1 - no unused assert macros

#   Failed test 'no unused assert macros'
#   at t/codingstd/c_arg_assert.t line 67.
# unused assert macros found:
# /home/jimk/gitwork/parrot/src/platform/generic/dl.c: find_handle_entry
# /home/jimk/gitwork/parrot/src/platform/generic/dl.c: push_handle_entry
# /home/jimk/gitwork/parrot/src/platform/generic/dl.c: remove_handle_entry
# 3 unused assert macros found in total.
ok 2 - macros used in correct position
# Looks like you failed 1 test of 2.
Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/2 subtests

Test Summary Report
-------------------
t/codingstd/c_arg_assert.t (Wstat: 256 Tests: 2 Failed: 1)
   Failed test:  1
   Non-zero exit status: 1
#####

Normally, when I see this error, I know that I can add a line under the 
header for 'myfunction' that says:  ASSERT_ARGS(my_function)

#####
$ git diff -- ./src
diff --git a/src/platform/generic/dl.c b/src/platform/generic/dl.c
index d9501dc..36f9bce 100644
--- a/src/platform/generic/dl.c
+++ b/src/platform/generic/dl.c
@@ -84,6 +84,7 @@ PARROT_CAN_RETURN_NULL
  static void *
  find_handle_entry(ARGIN(const void *handle))
  {
+    ASSERT_ARGS(find_handle_entry)
      const struct handle_entry *e;

      for (e = handle_list; e; e = e->next) {
@@ -97,6 +98,7 @@ find_handle_entry(ARGIN(const void *handle))
  static void
  remove_handle_entry(ARGIN(void *handle))
  {
+    ASSERT_ARGS(remove_handle_entry)
      if (handle_list) {
          if (handle_list->handle == handle) {
              struct handle_entry * const p = handle_list;
#####

And, indeed, these two additions cleared up 2 of the 3 failures in 
c_arg_assert.t.  But when I tried the same thing on push_handle_entry(), 
I get horrible test errors such as this:

#####
===(    5604;18  40/50  26/47  11/38   1/60 )===========================
#   Failed test 'load library fails'
#   at t/pmc/nci.t line 43.
# Exited with error code: [SIGNAL 6]
# Received:
# src/platform/generic/dl.c:70: failed assertion 'handle'
# Backtrace - Obtained 24 stack frames (max trace depth is 32).
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x400a864a]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_confess+0x9a) 
[0x400a87fa]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x40112958]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x401129ec]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x4009f41d]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x4009f72f]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_dyn_load_lib+0x13f) 
[0x4009ff3f]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x40091c84]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x400f4458]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x400f3f2a]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x400cb535]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_pcc_invoke_from_sig_object+0x18e) 
[0x400c429e]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_ext_call+0x103) 
[0x400aa013]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x401fdaf1]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_pcc_invoke_from_sig_object+0x13c) 
[0x400c424c]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_ext_call+0x103) 
[0x400aa013]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x400fb7c0]
# /home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0 [0x400fb84e]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_cx_begin_execution+0x11d) 
[0x400fb9fd]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_pf_execute_bytecode_program+0x185) 
[0x40107be5]
# 
/home/jimk/gitwork/parrot/blib/lib/libparrot.so.4.2.0(Parrot_api_run_bytecode+0x15a) 
[0x400a30ca]
# ./parrot [0x8049f9c]
# /lib/libc.so.6(__libc_start_main+0xe5) [0x40e88455]
# ./parrot [0x8048fd1]
# Attempting to get PIR backtrace.  No guarantees.  Here goes...
# current instr.: 'test' pc 0 (/home/jimk/gitwork/parrot/t/pmc/nci_1.pir:4)
# called from Sub '__PARROT_ENTRY_MAIN__' pc 359 
(frontend/parrot2/prt0.pir:127)
#
# Expected:
# undefined
#

#####
I cannot diagnose why adding ASSERT_ARGS(push_handle_entry) causes these 
problems.

Can someone (e.g., alester or nine, who have been working on this file) 
take a look at this?

And, while you're at it, could you write documentation for these three 
functions?  (If there had been some documentation, I might have had more 
of a clue as to what to do with the assert.)

Thank you very much.
Jim Keenan