* @author Michal Sojka <sojkam1@fel.cvut.cz>
* @date Fri Aug 29 09:37:27 2008
*
- * @brief Public interface to FORB. To be used by servers and clients.
+ * @brief Public interface to FORB. To be used by applications (both servers and clients).
*
*
*/
+/**
+@mainpage
+
+@section Introduction
+
+FORB is a CORBA-like middleware build on top of FOSA (FRESCOR
+Operating System Adaptation). Its main purpose is to provide unified
+in-process, inter-process and inter-node communication mechanism
+needed for implementation of FRESCOR in modular way. FORB is heavily
+inspired by CORBA, but provides only a very limited number of CORBA
+features.
+
+FORB supports one communication primitive, which is synchronous call
+of a remote method. This operation is mapped to a local function call,
+so that programmer cannot see the difference between the local and
+remote invocation. FORB implements all of the operations needed for
+such kind of communication which is:
+
+- serialization and deserialization of parameters and return values,
+- communication protocol to pass requests and replies between
+ processes,
+- finding the process, where the remote operation is implemented.
+
+FORB is composed of the two following components:
+- IDL compiler (called @c forb-idl) and
+- FORB runtime represented by @c libforb library.
+
+This documentation documents the @c libforb library. The IDL compiler
+is derived form Orbit project, and its documentation is out of scope
+of this document.
+
+@section Compilation
+
+See README file.
+
+@section Usage
+
+To use FORB in an application, an IDL (Interface Description Language)
+file has to be created first. This IDL file describes the interfaces
+used in the the application, their methods, parameters and types. The
+IDL language is similar to a subset of C language and is defined in <a
+href="http://www.omg.org/spec/CORBA/3.1/Interfaces/PDF/">OMG CORBA
+specification version 3.1, part 1</a> (chapter 7: OMG IDL Syntax and
+Semantics).
+
+An example IDL file called @c myinterface.idl can look like this:
+@include tests-idl/myinterface.idl
+
+It defines the interface called @c myinterface and some other
+(non-basic) types used in interface methods. To implement this
+interface, we process this file with the IDL compiler:
+
+\verbatim
+$ forb-idl myinterface.idl
+\endverbatim
+
+It generates four files: @c myinterface.h, @c myinterface-stubs.c, @c
+myinterface-skels.c and @c myinterface-common.c.
+
+The code of a server which implements the first two methods of this
+interface could look like this:
+
+@include tests-idl/example_server.c
+
+We have to compile this file and link it with @c -skels.c and @c
+-common.c files and the following libraries (under Linux): forb fosa
+pthread rt ulut.
+
+The client code which uses our implementation of @c myinterface could
+look like this:
+
+@include tests-idl/example_client.c
+
+It has to be compiled and linked with @c myinterface-stubs.c and @c
+myinterface-common.c files and with the following libraries (under
+Linux): forb fosa pthread rt ulut.
+
+Note that in these examples we intentionally skipped checking for
+errors to achieve more readable code.
+*/
+
+
#ifndef FORB_H
#define FORB_H
+#include <forb/forb-idl.h>
#include <forb/basic_types.h>
#include <fosa.h>
#include <forb/types.h>
+#include <forb/executor.h>
+#include <forb/object_type.h>
-
-/**
- * FORB exception types. Inspired by CORBA's standard system
- * exceptions.
- */
-enum forb_exception {
- FORB_EX_NONE, /* 0 */
- FORB_EX_UNKNOWN, /* 1 */
- FORB_EX_BAD_PARAM, /* 2 */
- FORB_EX_NO_MEMORY, /* 3 */
- FORB_EX_IMP_LIMIT, /* 4 */
- FORB_EX_COMM_FAILURE, /* 5 */
- FORB_EX_INV_OBJREF, /* 6 */
- FORB_EX_NO_PERMISSION, /* 7 */
- FORB_EX_INTERNAL, /* 8 */
- FORB_EX_MARSHAL, /* 9 */
- FORB_EX_INITIALIZE, /* 10 */
- FORB_EX_NO_IMPLEMENT, /* 11 */
- FORB_EX_BAD_OPERATION, /* 12 */
- FORB_EX_NO_RESOURCES, /* 13 */
- FORB_EX_NO_RESPONSE, /* 14 */
- FORB_EX_TRANSIENT, /* 15 */
- FORB_EX_FREE_MEM, /* 16 */
- FORB_EX_INV_IDENT, /* 17 */
- FORB_EX_INV_FLAG, /* 18 */
- FORB_EX_DATA_CONVERSION, /* 19 */
- FORB_EX_OBJECT_NOT_EXIST, /* 20 */
- FORB_EX_TIMEOUT, /* 21 */
-};
-
-struct forb_env {
- enum forb_exception major;
-};
-
-typedef struct forb_env CORBA_Environment;
-
-static inline CORBA_boolean forb_exception_occured(CORBA_Environment *env)
-{
- return (env->major != FORB_EX_NONE);
-}
-
-
-struct forb_object;
-
-/** Opaque object reference type. */
-typedef struct forb_object *forb_object;
-typedef forb_object CORBA_Object;
-
-/** Object reference type for ORB pseudo object. */
-typedef forb_object forb_orb;
-
+#ifdef __cplusplus
+extern "C" {
+#endif
/* Incomplete types - declared in forb-internal.h */
struct forb_interface;
typedef struct forb_interface forb_interface_t;
-struct forb_object;
-
-#define FORB_METHOD_INDEX(m) (m ## __method_index)
+typedef struct forb_init_attr {
+ const char *orb_id; /**< Name of the FORB used for debugging purposes */
+ void (*peer_discovery_callback)(const forb_orb peer_orb, const char *orb_id);
+ void (*peer_dead_callback)(const forb_orb peer_orb, const char *orb_id);
+ uint16_t fixed_tcp_port; /**< If we want FORB's inet protocol to listen on a fixed port... */
+ forb_server_id fixed_server_id; /**< If we do not want the ID to be random. (HACK) */
+ bool redistribute_hellos;
+} forb_init_attr_t;
/**
* Initializes FORB. This function has to be called before any other
* FORB function.
*
- * Any command line arguments used by FORB are removed from the array
- * and @a argc and @a argv are updated accordingly.
+ * Any command line arguments used by FORB are removed from the @a
+ * argv array and @a argc is updated accordingly.
+ *
+ * @note Currently, no command line arguments are used by FORB.
*
* @param argc a pointer to the number of command line arguments.
* @param argv a pointer to the array of command line arguments.
- * @param orb_id Name of the FORB used for debugging purposes.
+ * @param attr attributes that control FORB initialization.
*
* @return FORB object reference of NULL in case of error.
*/
-forb_orb forb_init(int *argc, char **argv[], const char *orb_id);
+forb_orb forb_init(int *argc, char **argv[], const forb_init_attr_t *attr);
/**
* Deallocates all resources consumed by FORB.
*/
void forb_destroy(forb_orb orb);
-#define forb_malloc(size) malloc(size)
-#define forb_free(ptr) free(ptr)
-
-#define CORBA_malloc(size) forb_malloc(size)
-#define CORBA_free(ptr) forb_free(ptr)
-
-forb_object
-forb_object_new(forb_orb orb,
- forb_server_id *server_id,
- forb_object_key key);
void
forb_object_release(forb_object obj);
-void
-forb_register_reference(const forb_orb orb, const char *id, forb_object object);
+forb_object
+forb_object_duplicate(const forb_object obj);
+
+void *
+forb_instance_data(const forb_object obj);
+
+int
+forb_register_reference(forb_object object, const char *name);
+
+int
+forb_unregister_reference(forb_orb orb, const char *name);
forb_object
-forb_resolve_reference(const forb_orb orb, const char *id);
+forb_resolve_reference(const forb_orb orb, const char *name);
forb_object
forb_string_to_object(const forb_orb orb, const char *string);
char *
forb_object_to_string(const forb_object obj);
+bool forb_object_is_stale(forb_object object);
+
+forb_orb
+forb_get_orb_of(const forb_object obj);
+
+void
+forb_get_server_id(const forb_object obj, forb_server_id *dest);
+
+void
+forb_get_req_source(const forb_object obj, forb_server_id *req_source);
+
+const char *
+forb_strerror(CORBA_Environment *env);
+
+void
+forb_daemon_prepare(const char *pid);
+
+void
+forb_daemon_ready();
+
+int
+forb_signal_server_ready();
+
+#ifdef __cplusplus
+} /* extern "C"*/
+#endif
+
#endif
projects / frescor / forb.git / blobdiff