Module: xenomai-forge
Branch: master
Commit: 33befdda4492710e8d793781c1222e7a261b7b57
URL:    
http://git.xenomai.org/?p=xenomai-forge.git;a=commit;h=33befdda4492710e8d793781c1222e7a261b7b57

Author: Philippe Gerum <r...@xenomai.org>
Date:   Fri Nov 18 09:26:54 2011 +0100

alchemy: documentation

---

 lib/alchemy/alarm.c |   47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 47 insertions(+), 0 deletions(-)

diff --git a/lib/alchemy/alarm.c b/lib/alchemy/alarm.c
index c86fc6d..801a6a2 100644
--- a/lib/alchemy/alarm.c
+++ b/lib/alchemy/alarm.c
@@ -80,6 +80,50 @@ static void alarm_handler(struct timerobj *tmobj)
        acb->handler(acb->arg);
 }
 
+/**
+ * @fn int rt_alarm_create(RT_ALARM *alarm,const char *name,void 
(*handler)(void *arg),void *arg)
+ * @brief Create an alarm object.
+ *
+ * Create an object triggering an alarm routine at a specified time in
+ * the future. Alarms can be periodic or oneshot, depending on the
+ * reload interval value passed to rt_alarm_start().
+ *
+ * @param alarm The address of an alarm descriptor which can be later
+ * used to identify uniquely the created object, upon success of this
+ * call. A bitwise copy of any valid alarm descriptor refers to the
+ * same object than the original descriptor points to.
+ *
+ * @param name An ASCII string standing for the symbolic name of the
+ * alarm. When non-NULL and non-empty, a copy of this string is used
+ * for indexing the created alarm into the object registry.
+ *
+ * @param handler The address of the routine to call when the alarm
+ * expires. This routine is passed the @a arg value.
+ *
+ * @param arg A user-defined opaque argument passed to the @a handler.
+ *
+ * @return 0 is returned upon success. Otherwise:
+ *
+ * - -ENOMEM is returned if the system fails to get memory from the
+ * local pool in order to create the alarm.
+ *
+ * - -EEXIST is returned if the @a name is conflicting with an already
+ * registered object.
+ *
+ * - -EPERM is returned if this service was called from an
+ * asynchronous context.
+ *
+ * Calling context:
+ *
+ * - Regular POSIX threads
+ * - Xenomai threads
+ *
+ * Rescheduling: possible.
+ *
+ * @note Alarms are process-private objects and thus cannot be shared
+ * by multiple processes, even if the latter belong to the same
+ * session.
+ */
 int rt_alarm_create(RT_ALARM *alarm, const char *name,
                    void (*handler)(void *arg),
                    void *arg)
@@ -88,6 +132,9 @@ int rt_alarm_create(RT_ALARM *alarm, const char *name,
        struct service svc;
        int ret;
 
+       if (threadobj_irq_p())
+               return -EPERM;
+
        COPPERPLATE_PROTECT(svc);
 
        acb = pvmalloc(sizeof(*acb));


_______________________________________________
Xenomai-git mailing list
Xenomai-git@gna.org
https://mail.gna.org/listinfo/xenomai-git

Reply via email to