Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

[cleanup] stdlib: Tidy up, remove debug statements and documentation …

…for cursor.opa.
  • Loading branch information...
commit 28fc00d066f413eae368780fadf8adc5352b5e37 1 parent 9eb005c
@nrs135 nrs135 authored
View
20 stdlib/apis/mongo/MongoDb.opa
@@ -1095,7 +1095,7 @@ type foreign('a,'b,'c,'d,'e) = {
type collection_cursor('a) = {
collection: collection('a);
- cursor: Cursor.cursor;
+ cursor: Mongo.cursor;
query: select('a);
ty: OpaType.ty;
ignore_incomplete: bool;
@@ -1199,11 +1199,11 @@ Collection : Collection = {{
find_one_doc(c:collection('value), select:select('value)): Mongo.result =
ns = c.db.dbname^"."^c.db.collection
- Cursor.find_one(c.db.mongo,ns,select,c.db.fields,c.db.orderby)
+ MongoCursor.find_one(c.db.mongo,ns,select,c.db.fields,c.db.orderby)
find_one_unsafe(c:collection('value), select:select('value), ignore_incomplete:bool): outcome('result,Mongo.failure) =
ns = c.db.dbname^"."^c.db.collection
- (match Cursor.find_one(c.db.mongo,ns,select,c.db.fields,c.db.orderby) with
+ (match MongoCursor.find_one(c.db.mongo,ns,select,c.db.fields,c.db.orderby) with
| {success=doc} ->
(match Bson.b2o_incomplete(doc, @typeval('result), ignore_incomplete) with
| {found=v} -> {success=(Magic.id(v):'result)}
@@ -1218,7 +1218,7 @@ Collection : Collection = {{
: outcome(collection_cursor('result),Mongo.failure) =
ns = c.db.dbname^"."^c.db.collection
//do println("query_unsafe:\n'value={OpaType.to_pretty(@typeval('value))}\n'result={OpaType.to_pretty(@typeval('result))}")
- match Cursor.find(c.db.mongo,ns,select,c.db.fields,c.db.orderby,c.db.limit,c.db.skip,c.db.query_flags) with
+ match MongoCursor.find(c.db.mongo,ns,select,c.db.fields,c.db.orderby,c.db.limit,c.db.skip,c.db.query_flags) with
| {success=cursor} ->
{success={collection=@unsafe_cast(c); ~cursor; query=@unsafe_cast(select); ty=@typeval('result); ~ignore_incomplete}}
| {~failure} -> {~failure}
@@ -1227,12 +1227,12 @@ Collection : Collection = {{
query_unsafe(c, select, false)
first(cc:collection_cursor('value)): outcome(collection_cursor('value),Mongo.failure) =
- _ = Cursor.reset(cc.cursor)
+ _ = MongoCursor.reset(cc.cursor)
query(cc.collection, cc.query)
next(cc:collection_cursor('value)): (collection_cursor('value),outcome('value,Mongo.failure)) =
- cursor = Cursor.next(cc.cursor)
- match Cursor.check_cursor_error(cursor) with
+ cursor = MongoCursor.next(cc.cursor)
+ match MongoCursor.check_cursor_error(cursor) with
| {success=doc} ->
//do println("next:\n doc={Bson.to_pretty(doc)}\n ty={OpaType.to_pretty(cc.ty)}")
(match Bson.b2o_incomplete(doc, cc.ty, cc.ignore_incomplete) with
@@ -1240,10 +1240,10 @@ Collection : Collection = {{
| {not_found} -> ({cc with ~cursor},{failure={Error="Collection.next: not found"}})
| {incomplete} -> ({cc with ~cursor},{failure={Incomplete}}))
| {~failure} ->
- cursor = Cursor.reset(cursor)
+ cursor = MongoCursor.reset(cursor)
({cc with ~cursor},{~failure})
- has_more(cc:collection_cursor('value)): bool = Cursor.valid(cc.cursor)
+ has_more(cc:collection_cursor('value)): bool = MongoCursor.valid(cc.cursor)
find_all_unsafe(c:collection('value), select:select('value), ignore_incomplete:bool): outcome(list('result),Mongo.failure) =
//do println("find_all:\n 'value={OpaType.to_pretty(@typeval('value))}\n 'result={OpaType.to_pretty(@typeval('result))}")
@@ -1316,7 +1316,7 @@ Collection : Collection = {{
// TODO: map-reduce
- kill(cc:collection_cursor('value)): collection_cursor('value) = { cc with cursor=Cursor.reset(cc.cursor) }
+ kill(cc:collection_cursor('value)): collection_cursor('value) = { cc with cursor=MongoCursor.reset(cc.cursor) }
}}
View
20 stdlib/apis/mongo/commands.opa
@@ -156,7 +156,7 @@ Commands = {{
* are other elements in the reply.
**/
run_command(m:Mongo.db, ns:string, command:Bson.document): Mongo.result =
- match Cursor.find_one(m, ns^".$cmd", command, {none}, {none}) with
+ match MongoCursor.find_one(m, ns^".$cmd", command, {none}, {none}) with
| {success=bson} -> MongoDriver.check_ok(bson)
| {~failure} -> {~failure}
@@ -336,7 +336,7 @@ Commands = {{
(match query_opt with | {some=query} -> [H.doc("query",query)] | {none} -> [])])
match run_command(m, db, cmd) with
| {success=bson} ->
- //do println("Cursor.distinct: bson={Bson.to_pretty(bson)}")
+ //do println("MongoCursor.distinct: bson={Bson.to_pretty(bson)}")
// TODO: stats
(match Bson.find(bson,"values") with
| {some=[{name=k; value={Array=d}}]} -> {success=[H.arr(k,List.rev(d))]}
@@ -351,10 +351,10 @@ Commands = {{
[H.str("ns",coll), H.doc("key",key), H.code("$reduce",reduce), H.doc("initial",initial)],
(match cond_opt with | {some=cond} -> [H.doc("cond",cond)] | {none} -> [H.null("cond")]),
(match finalize_opt with | {some=finalize} -> [H.code("finalize",finalize)] | {none} -> [])]))]
- //do println("Cursor.group: group={Bson.to_pretty(group)}")
+ //do println("MongoCursor.group: group={Bson.to_pretty(group)}")
match run_command(m, db, group) with
| {success=bson} ->
- //do println("Cursor.group: bson={Bson.to_pretty(bson)}")
+ //do println("MongoCursor.group: bson={Bson.to_pretty(bson)}")
{success=bson}
| {~failure} -> {~failure}
@@ -382,17 +382,17 @@ Commands = {{
/**
* Query the config.shards database, gives a list of shards.
**/
- findShards(m:Mongo.db, query:Bson.document): Mongo.results = Cursor.find_all(m, "config.shards", query, 100)
+ findShards(m:Mongo.db, query:Bson.document): Mongo.results = MongoCursor.find_all(m, "config.shards", query, 100)
/**
* Query the config.databases database, gives a list of shard information about databases.
**/
- findDatabases(m:Mongo.db, query:Bson.document): Mongo.results = Cursor.find_all(m, "config.databases", query, 100)
+ findDatabases(m:Mongo.db, query:Bson.document): Mongo.results = MongoCursor.find_all(m, "config.databases", query, 100)
/**
* Query the config.locks database, gives information about the shard balancer.
**/
- findBalancer(m:Mongo.db): Mongo.results = Cursor.find_all(m, "config.locks", [H.str("_id","balancer")], 100)
+ findBalancer(m:Mongo.db): Mongo.results = MongoCursor.find_all(m, "config.locks", [H.str("_id","balancer")], 100)
/**
* Low-level, set config.settings balancer value. Valid objects are "stopped" and "start/stop".
@@ -421,7 +421,7 @@ Commands = {{
/**
* Query the config.chunks database, gives a information about shard distribution.
**/
- findChunks(m:Mongo.db, query:Bson.document): Mongo.results = Cursor.find_all(m, "config.chunks", query, 100)
+ findChunks(m:Mongo.db, query:Bson.document): Mongo.results = MongoCursor.find_all(m, "config.chunks", query, 100)
/**
* Add a shard to a database.
@@ -496,9 +496,9 @@ Commands = {{
(match Bson.dot_int(doc,"remaining.dbs") with
| {some=0} | {none} -> {success=doc}//??failure
| _ ->
- (match Cursor.find_all(m, "config.databases", [H.str("primary",shard)], 100) with
+ (match MongoCursor.find_all(m, "config.databases", [H.str("primary",shard)], 100) with
| {success=dbs} ->
- (match Cursor.find_all(m, "config.shards", [], 100) with
+ (match MongoCursor.find_all(m, "config.shards", [], 100) with
| {success=[]} -> {failure={Error="No shards to move primary"}}
| {success=shards} ->
do println("dbs={Bson.to_pretty_list(dbs)}\nshards={Bson.to_pretty_list(shards)}")
View
167 stdlib/apis/mongo/cursor.opa
@@ -26,7 +26,7 @@
/**
* {1 About this module}
*
- * Module [Cursor] has the cursor handling routines.
+ * Module [MongoCursor] has the cursor handling routines.
*
* {1 Where should I start?}
*
@@ -34,40 +34,43 @@
*
**/
-/* Major TODOs, there are minor ones elsewhere. */
-// TODO: sort function for cursors
-
/**
- * type Cursor.cursor:
- * - Contains all the parameters for an op_query call.
- * - Stores the reply.
- * - Handles indexes into the list of documents returned and
- * keeps a note of the last document parsed.
- * - Also handles the cursor ID.
- * - Use Cursor.reset when not needed, this will generate a
- * kill_cursors call to the server to clean up.
+ * type [Mongo.cursor]:
+ *
+ * Contains all the parameters for an OP_QUERY call.
+ *
+ * Stores the reply.
+ *
+ * Handles indexes into the list of documents returned and
+ * keeps a note of the last document parsed.
+ *
+ * Also handles the cursor ID.
+ *
+ * Use [MongoCursor.reset] when not needed, this will generate a
+ * [kill_cursors] call to the server to clean up.
**/
-type Cursor.cursor = {
- mongo : Mongo.db;
- ns : string;
- flags : int;
- skip : int;
- limit : int;
- query : option(Bson.document);
- fields : option(Bson.document);
- orderby : option(Bson.document);
- query_sent : bool;
- cid : Mongo.cursorID;
- reply : option(Mongo.reply);
- returned : int;
- current : int;
- doc : Bson.document;
- killed : bool;
- error : string
+@abstract
+type Mongo.cursor = {
+ mongo : Mongo.db;
+ ns : string;
+ flags : int;
+ skip : int;
+ limit : int;
+ query : option(Bson.document);
+ fields : option(Bson.document);
+ orderby : option(Bson.document);
+ query_sent : bool;
+ cid : Mongo.cursorID;
+ reply : option(Mongo.reply);
+ returned : int;
+ current : int;
+ doc : Bson.document;
+ killed : bool;
+ error : string
}
@server_private
-Cursor = {{
+MongoCursor = {{
@private H = Bson.Abbrevs
@@ -76,10 +79,9 @@ Cursor = {{
/**
* Bare cursor initialize.
*
- * {b Warning:} Note that each time you create a cursor it generates buffers to talk to
- * the MongoDB server. Remember to cleanup cursor objects with [Cursor.reset].
+ * {b Warning:} Remember to cleanup cursor objects with [MongoCursor.reset].
**/
- init(mongo:Mongo.db, ns:string): Cursor.cursor =
+ init(mongo:Mongo.db, ns:string): Mongo.cursor =
{ ~mongo;
~ns;
flags = 0;
@@ -103,20 +105,20 @@ Cursor = {{
*
* These are named as for the arguments to a [MongoDriver.query] call.
**/
- set_flags(c:Cursor.cursor, flags:int): Cursor.cursor = { c with ~flags }
- set_skip(c:Cursor.cursor, skip:int): Cursor.cursor = { c with ~skip }
- set_limit(c:Cursor.cursor, limit:int): Cursor.cursor = { c with ~limit }
- set_query(c:Cursor.cursor, query:option(Bson.document)): Cursor.cursor = { c with ~query }
- set_fields(c:Cursor.cursor, fields:option(Bson.document)): Cursor.cursor = { c with ~fields }
- set_orderby(c:Cursor.cursor, orderby:option(Bson.document)): Cursor.cursor = { c with ~orderby }
+ set_flags(c:Mongo.cursor, flags:int): Mongo.cursor = { c with ~flags }
+ set_skip(c:Mongo.cursor, skip:int): Mongo.cursor = { c with ~skip }
+ set_limit(c:Mongo.cursor, limit:int): Mongo.cursor = { c with ~limit }
+ set_query(c:Mongo.cursor, query:option(Bson.document)): Mongo.cursor = { c with ~query }
+ set_fields(c:Mongo.cursor, fields:option(Bson.document)): Mongo.cursor = { c with ~fields }
+ set_orderby(c:Mongo.cursor, orderby:option(Bson.document)): Mongo.cursor = { c with ~orderby }
- tailable(c:Cursor.cursor): Cursor.cursor = { c with flags=Bitwise.lor(c.flags, MongoDriver.TailableCursorBit) }
+ tailable(c:Mongo.cursor): Mongo.cursor = { c with flags=Bitwise.lor(c.flags, MongoDriver.TailableCursorBit) }
@private
- set_error(c:Cursor.cursor, error:string): Cursor.cursor = { c with ~error; killed={true} }
+ set_error(c:Mongo.cursor, error:string): Mongo.cursor = { c with ~error; killed={true} }
@private
- reply(c:Cursor.cursor, reply_opt:option(Mongo.reply), name:string, query_sent:bool): Cursor.cursor =
+ reply(c:Mongo.cursor, reply_opt:option(Mongo.reply), name:string, query_sent:bool): Mongo.cursor =
match reply_opt with
| {some=reply} ->
cursorID = MongoDriver.reply_cursorID(reply)
@@ -128,7 +130,7 @@ Cursor = {{
current = 0;
doc = error_document("Uninitialised document",-1);
}
- | {none} -> set_error(c,"Cursor.{name}: no reply")
+ | {none} -> set_error(c,"MongoCursor.{name}: no reply")
/**
* Perform an OP_QUERY call to the database server based on the parameters
@@ -139,7 +141,7 @@ Cursor = {{
* Note that no tests are performed on the reply, there are other routines which
* examine the content of the reply. You may, however, get a comms error here.
**/
- op_query(c:Cursor.cursor): Cursor.cursor =
+ op_query(c:Mongo.cursor): Mongo.cursor =
if not(c.killed) && Option.is_some(c.query)
then
query = (match c.orderby with
@@ -148,38 +150,38 @@ Cursor = {{
//do println("op_query: query={Bson.to_pretty(query)}") <-- redundant, we've got logging now
reply(c,MongoDriver.query(c.mongo, c.flags, c.ns, c.skip, c.limit, query, c.fields),"op_query",{true})
else set_error(c,(if c.killed
- then "Cursor.op_query: already killed"
- else "Cursor.op_query: no query"))
+ then "MongoCursor.op_query: already killed"
+ else "MongoCursor.op_query: no query"))
/**
* Perform an OP_GETMORE call, if a valid cursor ID exists in the cursor.
**/
- get_more(c:Cursor.cursor): Cursor.cursor =
+ get_more(c:Mongo.cursor): Mongo.cursor =
if not(c.killed) && not(MongoDriver.is_null_cursorID(c.cid))
then reply(c,MongoDriver.get_more(c.mongo, c.ns, c.limit, c.cid),"get_more",c.query_sent)
- else set_error(c,"Cursor.get_more: attempt to get more with dead cursor")
+ else set_error(c,"MongoCursor.get_more: attempt to get more with dead cursor")
/**
* Return the [n]'th document in the reply stored in a cursor.
*
- * This is a low-level routine, use [Cursor.next] to scan the returned values
+ * This is a low-level routine, use [MongoCursor.next] to scan the returned values
* while sending additional OP_GETMORE calls when necessary.
*/
- document(c:Cursor.cursor, n:int): Mongo.result =
+ document(c:Mongo.cursor, n:int): Mongo.result =
if n >= c.returned
- then {failure={Error="Cursor.document: document index out of range {n}"}}
+ then {failure={Error="MongoCursor.document: document index out of range {n}"}}
else
match c.reply with
| {some=reply} ->
(match MongoDriver.reply_document(reply,n) with
| {some=doc} -> {success=doc}
- | {none} -> {failure={Error="Cursor.document: no document"}})
- | {none} -> {failure={Error="Cursor.document: no reply"}}
+ | {none} -> {failure={Error="MongoCursor.document: no document"}})
+ | {none} -> {failure={Error="MongoCursor.document: no reply"}}
/**
* Return all the documents in the reply stored in a cursor.
**/
- all_documents(c:Cursor.cursor): outcome(list(Bson.document), Mongo.failure) =
+ all_documents(c:Mongo.cursor): outcome(list(Bson.document), Mongo.failure) =
match c.reply with
| {some=reply} ->
rec aux(n:int) =
@@ -189,10 +191,10 @@ Cursor = {{
| {some=doc} -> (doc +> (aux(n+1)))
| {none} -> (aux(n+1)))
{success=aux(0)}
- | {none} -> {failure={Error="Cursor.document: no reply"}}
+ | {none} -> {failure={Error="MongoCursor.document: no reply"}}
@private
- destroy(c:Cursor.cursor): Cursor.cursor =
+ destroy(c:Mongo.cursor): Mongo.cursor =
{ c with
error="<reset>";
doc=error_document("Dead cursor",-1);
@@ -206,12 +208,12 @@ Cursor = {{
* Deletes buffer storage and sends a OP_KILL_CURSOR call if a valid cursor
* ID still exists in the cursor.
**/
- reset(c:Cursor.cursor): Cursor.cursor =
+ reset(c:Mongo.cursor): Mongo.cursor =
if not(MongoDriver.is_null_cursorID(c.cid))
then
if MongoDriver.kill_cursors(c.mongo, [c.cid])
then destroy(c)
- else set_error(destroy(c),"Cursor.reset: error killing cursor")
+ else set_error(destroy(c),"MongoCursor.reset: error killing cursor")
else destroy(c)
/**
@@ -229,22 +231,22 @@ Cursor = {{
*
* {b Warning:} Does not check the return flags.
*/
- rec next(c:Cursor.cursor): Cursor.cursor =
+ rec next(c:Mongo.cursor): Mongo.cursor =
c = if not(c.query_sent) then op_query(c) else c
if Option.is_none(c.reply)
- then set_error(c,"Cursor.next: no reply")
+ then set_error(c,"MongoCursor.next: no reply")
else
// TODO: analyze return flags
// TODO: tailable cursors
if c.returned <= 0
then
tags = MongoDriver.reply_tags(MongoDriver.reply_responseFlags(Option.get(c.reply)))
- set_error(c,"Cursor.next: no data returned tags={MongoDriver.string_of_tags(tags)}")
+ set_error(c,"MongoCursor.next: no data returned tags={MongoDriver.string_of_tags(tags)}")
else
if c.current >= c.returned
then
if MongoDriver.is_null_cursorID(c.cid)
- then set_error({c with doc = error_document("Read past end of data",-1)},"Cursor.next: end of data")
+ then set_error({c with doc = error_document("Read past end of data",-1)},"MongoCursor.next: end of data")
else next(get_more(c))
else {c with
current=c.current+1;
@@ -261,39 +263,46 @@ Cursor = {{
/**
* Create and initialise cursor with given query and default options.
+ *
+ * Example: [start(m, ns, query, limit)]
+ *
* Intended to form a set of functions to enable the idiom: [for(start(...),(c -> ... next(c)),valid)].
+ *
* Note: you can't actually use the OPA initial for() function with this idiom without
* missing the last element (you can't update the loop variable within the conditional for end of loop).
- * Use the Cursor.for() function instead.
+ * Use the MongoCursor.for() function instead.
+ *
+ * Note: MongoDB seems to interpret limit=1 as "just send me one document".
+ * If you want this loop to scan all the documents you can't use limit=1.
+ * This routine prints a warning message because if you only want one document you
+ * would be better using [MongoCursor.find_one].
**/
- start(m:Mongo.db, ns:string, query:Bson.document, limit:int): Cursor.cursor =
- c = Cursor.init(m,ns)
- /* Note: MongoDB seems to interpret limit=1 as "just send me one document".
- * If you want this loop to scan all the documents you can't use limit=1.
- */
- c = Cursor.set_limit(c,(max(2,limit))) // FIXME: destroys order (-2 etc.)
- c = Cursor.set_query(c,{some=query})
- Cursor.next(c)
+ start(m:Mongo.db, ns:string, query:Bson.document, limit:int): Mongo.cursor =
+ c = init(m,ns)
+ do if limit == 1 then ML.warning("MongoCursor.start","Cursor with limit==1 will only return one document.",void)
+ c = set_limit(c,limit)
+ c = set_query(c,{some=query})
+ next(c)
/**
* Test if there is still data in a cursor.
**/
- valid(c:Cursor.cursor): bool =
+ valid(c:Mongo.cursor): bool =
not(c.killed)
&& ((not(c.query_sent) && Option.is_some(c.query)) // initialised but not run
|| ((c.returned > 0 && (c.current < c.returned)))) // run and still has data
/**
- * Full find function with all parameters.
+ * Full [find] function with all parameters.
*
* Creates a cursor with the given parameters and calls OP_QUERY to
* initiate communications.
*
- * The cursor value is then returned, you can then use [Cursor.next] to
+ * The cursor value is then returned, you can then use [MongoCursor.next] to
* scan along from there.
**/
find(m:Mongo.db, ns:string, query:Bson.document, fields:option(Bson.document), orderby:option(Bson.document),
- limit:int, skip:int, flags:int): outcome(Cursor.cursor,Mongo.failure) =
+ limit:int, skip:int, flags:int): outcome(Mongo.cursor,Mongo.failure) =
c = init(m, ns)
c = set_query(c, {some=query})
c = set_fields(c, fields)
@@ -317,7 +326,7 @@ Cursor = {{
* document. Will return a [failure] document if "$err" exists in
* the document.
**/
- check_cursor_error(c:Cursor.cursor): Mongo.result =
+ check_cursor_error(c:Mongo.cursor): Mongo.result =
if not(c.killed)
then check_err(c.doc)
else {failure={Error=c.error}}
@@ -325,6 +334,8 @@ Cursor = {{
/**
* Find the first matching document for the given namespace.
*
+ * Example: [find_one(m, ns, query, fields, orderby)]
+ *
* Creates and destroys a cursor.
**/
find_one(m:Mongo.db, ns:string,
@@ -336,12 +347,14 @@ Cursor = {{
c = set_limit(c, 1)
c = next(c)
outcome = check_cursor_error(c)
- _ = Cursor.reset(c)
+ _ = reset(c)
outcome
/**
* Find all matching documents for the given namespace.
*
+ * Example: [find_all(m, ns, query, limit)]
+ *
* Creates and destroys a cursor.
**/
find_all(m:Mongo.db, ns:string, query:Bson.document, limit:int): Mongo.results =
View
2  stdlib/apis/mongo/mongo.opa
@@ -28,7 +28,7 @@
*
* This is a binding for MongoDB for OPA, loosely based around the C drivers.
*
- * Module [Mongo] has low-level routines to talk to the database server, the only
+ * Module [MongoDriver] has low-level routines to talk to the database server, the only
* routines you should need are the [MongoDriver.open] and [MongoDriver.close] functions.
*
* {1 Where should I start?}
Please sign in to comment.
Something went wrong with that request. Please try again.