Change module command parameter types

This commit introduces safe session references that can be handled without
holding locks. This allows the safe searching of sessions with the unique
ID of the session.

Remove the use of raw pointers passed as strings. Change the comments of
the argument types and add more details to the parsing function
documentation.

include/maxscale/modulecmd.h

@@ -55,14 +55,12 @@ typedef struct
 #define MODULECMD_ARG_NONE        0 /**< Empty argument */
 #define MODULECMD_ARG_STRING      1 /**< String */
 #define MODULECMD_ARG_BOOLEAN     2 /**< Boolean value */
-#define MODULECMD_ARG_SERVICE     3 /**< Service name */
-#define MODULECMD_ARG_SERVER      4 /**< Server name */
-#define MODULECMD_ARG_SESSION     5 /**< SESSION pointer in string format */
-#define MODULECMD_ARG_SESSION_PTR 6 /**< Raw SESSION pointer */
-#define MODULECMD_ARG_DCB         7 /**< DCB pointer in string format*/
-#define MODULECMD_ARG_DCB_PTR     8 /**< Raw DCB pointer*/
-#define MODULECMD_ARG_MONITOR     9 /**< Monitor name */
-#define MODULECMD_ARG_FILTER      10 /**< Filter name */
+#define MODULECMD_ARG_SERVICE     3 /**< Service */
+#define MODULECMD_ARG_SERVER      4 /**< Server */
+#define MODULECMD_ARG_SESSION     6 /**< Session */
+#define MODULECMD_ARG_DCB         8 /**< DCB */
+#define MODULECMD_ARG_MONITOR     9 /**< Monitor */
+#define MODULECMD_ARG_FILTER      10 /**< Filter */
 #define MODULECMD_ARG_OUTPUT      11 /**< DCB suitable for writing results to.
                                           This should always be the first argument
                                           if the function requires an output DCB. */
@@ -157,6 +155,20 @@ const MODULECMD* modulecmd_find_command(const char *domain, const char *identifi
 /**
  * @brief Parse arguments for a command
  *
+ * The argument types expect different forms of input.
+ *
+ * | Argument type         | Expected input    |
+ * |-----------------------|-------------------|
+ * | MODULECMD_ARG_SERVICE | Service name      |
+ * | MODULECMD_ARG_SERVER  | Server name       |
+ * | MODULECMD_ARG_SESSION | Session unique ID |
+ * | MODULECMD_ARG_MONITOR | Monitor name      |
+ * | MODULECMD_ARG_FILTER  | Filter name       |
+ * | MODULECMD_ARG_STRING  | String            |
+ * | MODULECMD_ARG_BOOLEAN | Boolean value     |
+ * | MODULECMD_ARG_DCB     | Raw DCB pointer   |
+ * | MODULECMD_ARG_OUTPUT  | DCB for output    |
+ *
  * @param cmd Command for which the parameters are parsed
  * @param argc Number of arguments
  * @param argv Argument list in string format of size @c argc

include/maxscale/session.h

@@ -339,4 +339,24 @@ static inline bool session_set_autocommit(SESSION* ses, bool autocommit)
     return prev_autocommit;
 }
 
+/**
+ * @brief Get a session reference by ID
+ *
+ * This creates an additional reference to a session whose unique ID matches @c id.
+ *
+ * @param id Unique session ID
+ * @return Reference to a SESSION or NULL if the session was not found
+ *
+ * @note The caller must free the session reference by passing it to the
+ * @c session_put_ref function
+ */
+SESSION* session_get_ref(int id);
+
+/**
+ * @brief Release a session reference
+ *
+ * @param session Session reference to release
+ */
+void session_put_ref(SESSION *session);
+
 MXS_END_DECLS